Merge pull request #274 from LCSB-BioCore/mk-contribguide

unify contribution guides

.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`

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",