diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index f83fe6810..08f669615 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 09a5b80dc..2b887d8c6 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -49,6 +49,13 @@ index_md = replace(index_md, "\n" => acks) index_md = replace(index_md, "\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 7a06dd99a..000000000 --- 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.