|
| 1 | +## Contributor guidelines |
| 2 | + |
| 3 | +Anybody is welcome to contribute to the development of the RAVEN Toolbox, but please abide by the following guidelines. |
| 4 | + |
| 5 | +Each function should start with a commented section describing the function and explaining the parameters. Existing functions can clarify what style should be used. |
| 6 | + |
| 7 | +### Bugfixes, New Features and Functions |
| 8 | +* For any development, whether bug fixes, introducing new functions or new/updated features for existing functions: make a separate branch from `devel` and name the branch for instance after the function/feature you are fixing/developing. If you work on a fix, start the branch name with `fix/`, if you work on a feature, start the branch name with `feat/`. Examples: `fix/format_reactions` or `feat/new_algorithms`. |
| 9 | +* Make commits to this branch while developing. Aim for backward compatibility, and try to avoid very new MATLAB functions when possible, to accommodate users with older MATLAB versions. |
| 10 | +* When you are happy with your new function/feature, make a pull request to the `devel` branch. Also, see [Pull request](#pull-request) below. |
| 11 | + |
| 12 | +### Semantic Commits |
| 13 | +Use semantic commit messages to make it easier to show what you are aiming to do: |
| 14 | +* `chore`: updating binaries, KEGG or MetaCyc database files, etc. |
| 15 | +* `doc`: updating documentation (in `doc` folder) or explanatory comments in functions. |
| 16 | +* `feat`: new feature added, e.g. new function introduced / new parameters / new algorithm / etc. |
| 17 | +* `fix`: bugfix. |
| 18 | +* `refactor`: see [code refactoring](https://en.wikipedia.org/wiki/Code_refactoring). |
| 19 | +* `style`: minor format changes of functions (spaces, semi-colons, etc., no code change). |
| 20 | + |
| 21 | +Examples: |
| 22 | +``` |
| 23 | +feat: exportModel additional export to YAML |
| 24 | +chore: update KEGG model to version 83.0 |
| 25 | +fix: optimizeProb parsing results from Gurobi |
| 26 | +``` |
| 27 | +A more detailed explanation or comments can be left in the commit description. |
| 28 | + |
| 29 | +### External Software Update |
| 30 | +* Once the newer version for any external software (BLAST+, CD-HIT, DIAMOND, HMMER, MAFFT, WoLFPSORT) is available, identify the newest version which is simultaneously available for macOS, Unix/Linux and Windows |
| 31 | +* Create a separate branch from the `devel` branch and name it e.g. `chore/updateBinaries` |
| 32 | +* Commit the changes for each program and operating system separately, e.g. `chore: update HMMER (Win) to 3.2.1` |
| 33 | +* As soon as all binaries for particular program are updated through commits, update the corresponding license file, if available and place it in e.g. `software/blast+` directory. |
| 34 | +* Update the version number in `RAVENdir/software/version.txt` file. |
| 35 | +* Do some testing to ensure that the new binaries are working correctly. Upon successful tests, create a Pull Request to the `devel` branch. |
| 36 | + |
| 37 | +### Pull Requests |
| 38 | +* No changes should be directly committed to the `main` or `devel` branches. Commits are made to side branches, after which pull requests are made for merging with `main` or `devel`. |
| 39 | +* The person making the pull request and the one accepting the merge _cannot_ be the same person. |
| 40 | +* Typically, wait a few days before merging, to allow for other developers to inspect the pull request. |
| 41 | +* A merge with the mainbranch invokes a new release (see [versioning](#versioning)). |
| 42 | + |
| 43 | +### Versioning |
| 44 | +RAVEN Toolbox follows [semantic versioning](https://semver.org/). After each successful Pull Request (PR) to `main`, the `version.txt` file should be updated in a separate PR. When this PR is merged, a new [release](https://github.com/SysBioChalmers/RAVEN/releases) should be specified, with a list detailing the most significant changes since the previous release. |
| 45 | + |
| 46 | +Ensure that the documentation is also updated (in `devel`) before creating a PR to `main`. It can be updated by running `updateDocumentation()`. |
| 47 | + |
| 48 | +### Categorize Releases |
| 49 | +* PRs pushed into `main` should be patch releases by default. |
| 50 | +* Developers who push PRs to `devel` may propose target release categories (e.g. minor or patch) that can be commented on and discussed by reviewers and other developers. |
| 51 | +* As a result of the above step, minor releases hopefully can be determined. |
| 52 | +* To help the process of categorizing releases, some conditions are suggested qualification for minor releases: |
| 53 | + * with database updates (e.g. KEGG, MetaCyc) |
| 54 | + * script reusability (i.e. with parameter changes in RAVEN functions) |
| 55 | + * with binary file changes |
| 56 | + |
| 57 | +## Make a New Release |
| 58 | +* Start a PR from develop to main with summary of all PRs since the last release, titled "RAVEN 2.9.3" (replace 2.9.3 with the version of the next release) |
| 59 | +* Once ready, locally merge develop into main by accepting all changes using following commands, and push to origin: |
| 60 | + * `git checkout main` |
| 61 | + * `git pull` |
| 62 | + * `git merge -Xtheirs develop -m "RAVEN 2.9.3"` (replace 2.9.3 with the version of the next release) |
| 63 | + * `printf "2.9.3" > version.txt` (replace 2.9.3 with the version of the next release) |
| 64 | + * `git stage version.txt` |
| 65 | + * `git commite --amend --no-edit` |
| 66 | + * `git push` |
| 67 | +* Initiate a new release, with name and tag "v2.9.3" (replace 2.9.3 with the version of the next release) |
0 commit comments