diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index f83fe6810f4bffbe850f9067ce76f51f123d322a..08f6696159ee831e0e73b5a360b6b9293c5f2d06 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -3,65 +3,188 @@
:+1::tada: Thanks for taking the time to contribute to
[COBREXA.jl](https://github.com/LCSB-BioCore/COBREXA.jl)! :tada::+1:
+## How to report a bug or suggest an enhancement
+
+Please use the [GitHub issue
+tracker](https://github.com/LCSB-BioCore/COBREXA.jl/issues) to report any
+problems with the software, and discuss any potential questions about COBREXA
+use.
+
+Before creating bug reports, please check [the open
+issues](https://github.com/LCSB-BioCore/COBREXA.jl/issues), you might find
+out that the issue is already reported and known.
+
+General guidelines for reporting issues:
+
+- If creating a bug report, include a complete description of how we can
+ reproduce the bug, including e.g. links to datasets and any external scripts
+ used. Ideally, try to create a code snippet that causes the problem on a
+ fresh installation of COBREXA.jl (often called the "minimal crashing
+ example")
+- If possible, use the supplied issue templates and fill in all fields.
+- If your issue is already described in an issue that is "closed", do not
+ reopen it. Instead, open a new issue and include a link to the original
+ issue. (The fact that the original issue might have been mistakenly closed
+ may be an issue on its own.)
+- Enhancement proposals should refer a viable way for implementing the
+ enhancement. If there are multiple possibilities for implementation, we will
+ welcome a discussion about which one is optimal for COBREXA.jl.
+
## How to test a development version of the package?
-You can use the "develop" feature of Julia packaging system. One possible way
-is here:
+### Step 1: Load COBREXA.jl from the source from the git repository
+
+There are two ways that you can retrieve a local copy of the development repo:
+you can either clone the repository manually, or use Julia package manager to
+get a development version for you.
+
+#### Option 1: Using Julia package manager
+
+When you are used to using the Julia package manager for developing or
+contributing to packages, you can type:
+
+```julia
+(v1.6) pkg> dev COBREXA
+```
-1. Clone the repository as usual (or find your cloned copy), `cd` into the
- directory
-2. Start `julia`, type `]` to switch to the packaging interface and type
- `develop --local .`
-3. The package will be always recompiled and loaded from your local repository.
+This will install the `COBREXA` package locally and check it out for
+development. You can check the location of the package with:
-Alternatively, you can checkout the whole repository directly using Julia, by
-typing:
+```julia
+(v1.6) pkg> status
+ Status `~/.julia/environments/v1.4/Project.toml`
+ [a03a9c34] COBREXA v0.0.5 [`~/.julia/dev/COBREXA`]
```
-develop COBREXA
+
+The default location of the package is `~/.julia/dev/COBREXA`.
+
+#### Option 2: Cloning with `git` manually
+
+You can use `git` to get the sources as follows:
+
+```bash
+$ git clone git@github.com:LCSB-BioCore/COBREXA.jl.git
```
-That will create the repo for you in `~/.julia/dev/`, which you can use for
-development and pushing/pulling.
+When the cloning process finishes, you shold see the package cloned in a new
+directory `COBREXA.jl`. To install this version to your Julia, change to the
+directory first, and start Julia:
+```bash
+$ cd COBREXA.jl
+$ julia
+```
-## How to report a bug or suggest an enhancement
+With Julia, you can install the development version of the package from the
+directory as follows:
-Please use the [GitHub issue
-tracker](https://github.com/LCSB-BioCore/COBREXA.jl/issues) to report any
-problems with the software, and discuss any potential questions about COBREXA
-use.
+```julia
+(v1.6) pkg> add .
+```
-Before creating bug reports, please check [the open
-issues](https://github.com/LCSB-BioCore/COBREXA.jl/issues) as you might find
-out that you don't need to create one. When you are creating a bug report,
-please include as many details as possible. Fill out the required template, the
-information it asks for helps us resolve issues faster.
+(press `]` to get into the packaging environment)
-> If you find a Closed issue that seems like it is the same thing that
- you're experiencing, open a new issue and include a link to the original issue
- in the body of your new one.
+This adds the `COBREXA.jl` package and all its dependencies. You can verify
+that the installation worked by typing:
-If reporting issues, please do not forget to include a description of
-conditions under which the issue occurs; preferably a code snippet that can be
-run separately (sometimes termed "minimal crashing example").
+```julia
+(v1.6) pkg> status
+```
+
+If you are planning to develop the package, it is often easier to install the
+package in development mode, with `dev` command:
+
+```julia
+(v1.6) pkg> dev .
+```
+
+That causes the package to always load with whatever code changes that you
+added to the source directory.
+
+#### Finally: load COBREXA.jl
+
+With both of above options, you should get COBREXA.jl installed, which means
+that the following command should, without errors, load the package and make
+COBREXA.jl functions available for testing:
+
+```julia
+julia> using COBREXA
+```
+
+You may now freely modify the code and test the result.
+
+Remember that if you want to work in the environment of the package, you need
+to *activate* it. That causes, among other, that the additional dependencies
+specified with packaging `add` command will be written automaticaly to
+`Project.toml` file of your local COBREXA.jl clone, not to your global
+environment. Activation is simple: when in the directory of the package, just
+type the command into the packaging shell:
+
+```julia
+(v1.6) pkg> activate
+```
+
+### Step 2: Publish your changes
+
+You are expected to make a fork of the main COBREXA.jl repository, and open a
+pull request from that one to the `master` branch of the main repository.
+For creating the fork, just hit the "Fork" button on GitHub.
+
+After that, change the directory to your repository and adjust the remotes:
+
+```bash
+$ cd ~/.julia/dev/COBREXA # or any other directory, as needed
+$ git remote rename origin upstream # renames the origin (the main COBREXA.jl repo) to upstream
+$ git remote add origin git@github.com:yourUsername/COBREXA.jl.git # adds the link to your clone as new origin
+$ git fetch origin # fetches the refs from your repo
+```
+
+In the above code, change `yourUsername` is your GitHub username.
+
+When the renaming is done, start a new branch at `upstream/master`. In the code
+snippet, substitute `yn` for your initials (Your Name here) and give the new
+feature a better name than `somefeature`:
+```bash
+$ git checkout -b yn-somefeature origin/master
+```
+
+Commit any changes and features that you like to the new branch. When the
+commits look complete to you, push the branch to your repository fork:
+
+```bash
+$ git push -u origin yn-somefeature
+```
+
+This makes your changes visible in your repository. After that, you can
+navigate to [GitHub's pull request
+page](https://github.com/LCSB-BioCore/COBREXA.jl/pulls), where you should
+immediately see a big green button that helps you to create a pull request for
+this branch. Read the section below for precise details and guidelines on
+submitting the pull requests.
## How to submit a pull request (PR) with your modification/enhancement?
-1. Make a fork of the repository, commit the modifications in a separate branch.
-2. Make a PR, follow instructions in the PR template (if available). Describe
- the motivation and expected outcome for the users. Specifically, consider
- any possible incompatibilities, and the necessity to increment the version
- number after your changes are applied.
-3. Submit your pull request
-4. Verify that all status checks (tests, documentation) are passing. Make sure
- any new contribution is properly documented and tested (you may want to
- check with coverage tools, using `test --coverage` from the Julia packaging
- shell)
+1. **Make a fork of the repository**, commit the modifications in a **separate
+ branch** and push the branch to your fork.
+2. Make a pull request where you describe the motivation and expected outcome
+ for the users. Specifically, consider any possible incompatibilities, and
+ the necessity to increment the version number after your changes are
+ applied.
+3. After submitting the pull request, verify that all status checks (tests,
+ documentation) are passing. Make sure any new contribution is properly
+ documented and tested (you may want to check with coverage tools, using
+ `test --coverage` from the Julia packaging shell)
After you submitted a pull request, a label might be assigned that allows us
to track and manage issues and pull requests.
-## What is the workflow?
+**Tip**: if you commit many small, partial changes, you may help us save energy
+by prefixing your commit names with `[skip ci]`, which deactivates the CI
+trigger on that commit. With each skipped CI, you may save as much as 15Wh of
+energy. Testing just the "final" commit of the pull-request branch is
+sufficient.
+
+## For developers: What is the expected branch management/workflow?
The workflow is based on [GitLab
flow](https://docs.gitlab.com/ee/topics/gitlab_flow.html), i.e., a `master`
diff --git a/docs/make.jl b/docs/make.jl
index 09a5b80dc567938b1f6278d34ea4f5be1bdf72ea..2b887d8c692ea4fe4fd33f0867a53f7235be5546 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -49,6 +49,13 @@ index_md = replace(index_md, "<!--insert_acknowledgements-->\n" => acks)
index_md = replace(index_md, "<!--insert_ack_logos-->\n" => ack_logos)
open(f -> write(f, index_md), joinpath(@__DIR__, "src", "index.md"), "w")
+# copy the contribution guide
+cp(
+ joinpath("..", ".github", "CONTRIBUTING.md"),
+ joinpath("src", "howToContribute.md"),
+ force = true,
+)
+
# build the docs
makedocs(
modules = [COBREXA],
@@ -71,10 +78,19 @@ makedocs(
],
)
-# replace the link for index.md
-index_html = open(f -> read(f, String), joinpath(@__DIR__, "build", "index.html"))
-index_html = replace(index_html, "/docs/src/index.md" => "")
-open(f -> write(f, index_html), joinpath(@__DIR__, "build", "index.html"), "w")
+# replace the "edit this" links for the generated documentation
+function replace_in_doc(filename, replacement)
+ contents = open(f -> read(f, String), joinpath(@__DIR__, "build", filename))
+ contents = replace(contents, replacement)
+ open(f -> write(f, contents), joinpath(@__DIR__, "build", filename), "w")
+end
+
+replace_in_doc("index.html", "blob/master/docs/src/index.md" => "")
+replace_in_doc(
+ joinpath("howToContribute", "index.html"),
+ "blob/master/docs/src/howToContribute.md" => "",
+)
+
deploydocs(
repo = "github.com/$(ENV["TRAVIS_REPO_SLUG"]).git",
diff --git a/docs/src/howToContribute.md b/docs/src/howToContribute.md
deleted file mode 100644
index 7a06dd99a95da8351f58a1fadb2f3f78d0d34a7e..0000000000000000000000000000000000000000
--- a/docs/src/howToContribute.md
+++ /dev/null
@@ -1,137 +0,0 @@
-# How to contribute to/develop COBREXA
-
-If you want to contribute to the `COBREXA` package, please fork the present
-repository by following [these instructions](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo).
-
-## Step 1: Retrieve a local version of COBREXA
-
-There are two ways that you can retrieve a local copy of the package: one is to
-manually clone the forked repository, and the second one is to use the
-integrated Julia package manager.
-
-### Option 1: Manually clone your fork
-
-!!! warning "Warning"
- Please make sure you have _forked_ the repository, as described above.
-
-You can do this as follows from the command line:
-
-```bash
-$ git clone git@github.com:yourUsername/COBREXA.jl.git COBREXA.jl
-$ cd COBREXA.jl
-$ git checkout -b yourNewBranch origin/develop
-```
-
-where `yourUsername` is your Github username and `yourNewBranch` is the name of a new branch.
-
-Then, in order to develop the package, you can install your cloned version as
-follows (make sure you are in the `COBREXA.jl` directory):
-
-```julia
-(v1.1) pkg> add .
-```
-
-(press `]` to get into the packaging environment)
-
-This adds the `COBREXA.jl` package and all its dependencies. You can verify
-that the installation worked by typing:
-
-```julia
-(v1.1) pkg> status
-```
-
-If everything went smoothly, this should print something similar to:
-
-```julia
-(v1.1) pkg> status
- Status `~/.julia/environments/v1.1/Project.toml`
- [babc4406] COBREXA v0.1.0 #yourNewBranch (.)
-```
-
-Now, you can readily start using the `COBREXA` module:
-
-```julia
-julia> using COBREXA
-```
-
-### Option 2: Use the Julia package manager
-
-When you are used to using the Julia package manager for developing or
-contributing to packages, you can type:
-
-```julia
-(v1.1) pkg> dev COBREXA
-```
-
-This will install the `COBREXA` package locally and check it out for
-development. You can check the location of the package with:
-
-```julia
-(v1.1) pkg> status
- Status `~/.julia/environments/v1.4/Project.toml`
- [a03a9c34] COBREXA v0.0.5 [`~/.julia/dev/COBREXA`]
-```
-
-The default location of the package is `~/.julia/dev/COBREXA`.
-
-You can then set your remote by executing these commands in a regular shell:
-
-```bash
-$ cd ~/.julia/dev/COBREXA
-$ git remote rename origin upstream # renames the origin as upstream
-$ git remote add origin git@github.com:yourUsername/COBREXA.jl.git
-$ git fetch origin
-```
-
-where `yourUsername` is your Github username.
-
-!!! warning "Warning"
- Make sure that your fork is located at `github.com/yourUsername/COBREXA.jl`.
-
-Then, checkout a branch `yourNewBranch`:
-
-```bash
-$ cd ~/.julia/dev/COBREXA
-$ git checkout -b yourNewBranch origin/develop
-```
-
-Then, you can readily use the `COBREXA` package:
-
-```julia
-julia> using COBREXA
-```
-
-After making changes, precompile the package:
-
-```julia
-(v1.1) pkg> precompile
-```
-
-## Step 2: Activate COBREXA
-
-!!! warning "Warning"
- Please note that you cannot use the dependencies of COBREXA directly,
- unless they are installed separately or the environment has been activated:
-
-```julia
-(v1.1) pkg> activate .
-(COBREXA) pkg> instantiate
-```
-
-Now, the environment is activated (you can see it with the prompt change
-`(COBREXA) pkg>`). Now, you can use the dependency. For instance:
-
-```julia
-julia> using JuMP
-```
-
-!!! warning "Warning"
- If you do not `activate` the environment before using any of the
- dependencies, you will see a red error messages prompting you to install the
- dependency explicitly.
-
-## Step 3: Contribute!
-
-!!! tip "Tip"
- Adding `[skip ci]` in your commit message will skip CI from automatically
- testing that commit.