More docs

docs/additional-resources/openms-git-workflow.md

@@ -0,0 +1,197 @@
+OpenMS Git Workflow
+===================
+
+Before getting started, install latest version of git to avoid problems like GitHub https authentication errors
+(see [Troubleshooting cloning errors](https://docs.github.com/en/repositories/creating-and-managing-repositories/troubleshooting-cloning-errors) and a solution using [ssh](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories)).
+
+OpenMS follows the [git flow workflow](https://nvie.com/posts/a-successful-git-branching-model/). The difference is that
+merge commits are managed via pull requests instead of creating merge commits locally.
+
+## Naming conventions
+
+Naming conventions for the following apply:
+
+* A **local repository** is the repository that lies on your hard drive after cloning.
+* A **remote repository** is a repository on a git server such as GitHub.
+* A **fork** is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.
+* **Origin** refers to a remote repository that you have forked. Call this repository https://github.com/_YOURUSERNAME_/OpenMS.
+* **Upstream** refers to the original remote OpenMS repository. Call this repository https://github.com/OpenMS/OpenMS.
+
+## Create fork
+
+Start by [forking](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the OpenMS repository.
+
+To create a fork, click **Fork** under the main menu as shown below.
+
+![image info](../images/additional-resources/click-fork.png)
+
+## Clone your fork
+
+To obtain a local repository copy, clone your fork using:
+
+```bash
+$ git clone https://github.com/_YOURUSERNAME_/OpenMS.git
+```
+
+This will clone your fork (correctly labelled `origin` by default) into a local copy on your computer.
+
+## Link remote branches to your local working repository
+
+After cloning your fork, your local repository should be named origin. Validate this by executing:
+
+```bash
+$ git remote -v
+  origin https://github.com/_YOURUSERNAME_/OpenMS.git (fetch)
+  origin https://github.com/_YOURUSERNAME_/OpenMS.git (push)
+```
+
+Sync data between your local copy, your fork (`origin`) and the remote original OpenMS/OpenMS repository (`upstream`)
+by using the following command:
+
+```bash
+$ git remote add upstream https://github.com/OpenMS/OpenMS.git
+```
+Verify that upstream was added correctly by calling:
+
+```bash
+$ git remote -v
+  origin https://github.com/_YOURUSERNAME_/OpenMS.git (fetch)
+  origin https://github.com/_YOURUSERNAME_/OpenMS.git (push)
+  upstream https://github.com/OpenMS/OpenMS.git (fetch)
+  upstream https://github.com/OpenMS/OpenMS.git (push)
+
+```
+
+Fetch changes and new branches from your fork (`origin`) as well as from the central, upstream OpenMS repository by executing:
+
+```bash
+$ git fetch upstream
+$ git fetch origin
+```
+or
+
+```bash
+$ git fetch --all
+```
+
+Create a local branch using the following:
+
+```bash
+$ git checkout -b <insert branch-name>
+```
+
+Call `git branch -va` to display the status of local and remote branches. You should see an output that looks like this:
+
+```bash
+$ git branch -va
+* develop                         349ec48 Merge pull request #691 from cbielow/MGF_fix
+  feature/my_shiny_new_feature    3c05538 [FEATURE] added option to keep, ensure or reassign UIDs during conversion
+  remotes/origin/SILACAnalyzer    3ceae38 Fixed test.
+  remotes/origin/antilope         3fe5aa3 git-svn-id: https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/antilope@12117 6adb6e08-d915-0410-941f-83917bcadc18
+  remotes/origin/develop          349ec48 Merge pull request #691 from cbielow/MGF_fix
+  remotes/origin/master           b182ba5 [NOP] first commit after SVN import to git
+  remotes/origin/msnovogen        93a5e4c [OPT] For faster access to specific amino acids a ResidueServer was added.
+  remotes/upstream/HEAD           -> upstream/develop
+  remotes/upstream/SILACAnalyzer  3ceae38 Fixed test.
+  remotes/upstream/antilope       3fe5aa3 git-svn-id: https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/antilope@12117 6adb6e08-d915-0410-941f-83917bcadc18
+  remotes/upstream/develop        349ec48 Merge pull request #691 from cbielow/MGF_fix
+  remotes/upstream/master         b182ba5 [NOP] first commit after SVN import to git
+  remotes/upstream/msnovogen      93a5e4c [OPT] For faster access to specific amino acids a ResidueServer was added.
+```
+
+## Keep your fork in sync
+
+Keep your fork (`origin`) in sync with the OpenMS repository (`upstream`) by following the [GitHub instructions](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork).
+In summary, to keep your fork in sync:
+1. Fetch changes from upstream and update your local branch.
+2. Push your updated local branch to your fork (`origin`).
+
+```{tip}
+To keep track of others repositories, use `git fetch --all --prune` to update them as well. The option `--prune` tells
+git to automatically remove tracked branches if they got removed in the remote repository.
+```
+
+```bash
+$ git fetch --all --prune
+$ git checkout develop
+$ git merge --ff-only upstream/develop
+$ git push origin develop
+```
+Feel free to experiment within your fork. However, for your code needs to meet OpenMS quality standards to be merged
+into the OpenMS repository,
+
+Follow these rules:
+* Never commit directly to the `develop` or `master` branches as it will complicate the merge.
+* Try to start every feature from develop and not base features on other features.
+* Name the OpenMS remote `upstream` and always push directly to `origin` (`git push origin <branch-name>`).
+* When updating your fork, consider using `git fetch upstream` followed by `git merge --ff-only upstream/develop` to
+  avoid creating merge commits in `develop`.
+* If you never commit to `develop` this should always succeed and (if a commit accidentally went to develop) warn you
+  instead of creating a merge commit.
+
+## Create new feature
+
+All features start from `develop`.
+
+```bash
+$ git checkout develop
+$ git checkout -b feature/your-cool-new-feature
+```
+All commits related to this feature will then go into the branch `feature/your-cool-new-feature`.
+
+## Keeping your feature branch in sync with develop branch
+
+While working on your feature branch, it is usual that development continues and new features get integrated into the
+main development branch. This means your feature branch lags behind `develop`. To get your feature branch up-to-date,
+rebase your feature branch on `develop` using:
+
+```bash
+$ git checkout feature/myfeaturebranch
+$ git rebase develop
+```
+
+The above commands:
+
+1. Performs a rewind of your commits until the branching point.
+2. Applies all commits that have been integrated into `develop`.
+3. Reapplies your commits on top of the commits integrated into `develop`.
+
+For more information, refer to a [visual explanation of rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing).
+
+```{tip}
+Do not rebase published branches (e.g. branches that are part of a pull request). If you created a pull request, you
+should only add commits in your feature branch to fix things that have been discussed. After your pull request contains
+all fixes, you are ready to merge the pull request into develop without rebasing (see e.g. rebase-vs-merge).
+```
+
+## Adding a feature to OpenMS
+
+Features that should go into the main development line of OpenMS should be integrated via a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). This allows
+the development community of OpenMS to discuss the changes and suggest possible improvements.
+
+After opening the pull request via the GitHub web site, GitHub will try to create the pull request against the branch
+that you branched off from. Please check the branch that you are opening the pull request against before submitting the
+pull request. If any changes are made, a new pull request is required. Select
+**Allow others to make changes to this pull request** so that maintainers can directly help to solve problems.
+
+Open pull requests only after checking code-style, documentation and passing tests. Pull requests that do not pass CI
+or code review will not be merged until the problems are solved. It is recommended that you read the
+[pull request guidelines](pull-request-checklist.md) before you submit a pull request.
+
+## Update git submodules
+
+Start in your local `OpenMS/OpenMS` repository (on your feature/pull request branch).
+
+The following example uses a submodule called `THIRDPARTY`.
+
+```bash
+$ git submodule update --init THIRDPARTY
+$ cd THIRDPARTY
+# yes, in the submodules the default remote is origin
+# usually you want to pull the changes from master (e.g. after your pull request to OpenMS/THIRDPARTY has been merged)
+$ git pull origin master
+$ cd ..
+$ git status
+# Make sure that you see "modified:   THIRDPARTY (new commits)"
+$ git commit -am "updated submodule"
+```

docs/additional-resources/pull-request-checklist.md

@@ -0,0 +1,44 @@
+Pull Request Checklist
+======================
+
+Before opening a pull request, check the following:
+
+1. **Does the code build?**
+  Execute `make` (or your build system's equivalent, e.g., `cmake --build . --target ALL_BUILD --config Release` on Windows).
+2. **Do all tests pass?**
+   To check if all tests have passed, execute `ctest`.
+   If a test that is unrelated to your changes fails, check the [nightly builds](http://cdash.openms.de/index.php?project=OpenMS)
+   to see if the error is also in `develop`. If the error is in develop, [create a github issue](write-and-label-github-issues.md).
+3. **Is the code documented?**
+   Document all new classes, including their methods and parameters.
+   It is also recommended to document non-public members and methods.
+4. **Does the code introduce changes to the API?**
+   If the code introduces changes to the API, make sure that the documentation is up-to-date and that the Python bindings
+   (pyOpenMS) still work. For each change in the C++ API, make a change in the Python API wrapper via the `pyOpenMS/pxds/` files.
+5. **Have you completed regression testing?**
+   Make sure that you include a test in the test suite for:
+   - Public methods of a class
+   - TOPP tools
+   - Bug fixes
+
+Make sure to:
+
+- **Rebase before you open a pull request.**
+  To include all recent changes, rebase your branch on `develop` before opening a pull request.
+  If you pushed your branch to `origin` before rebasing, git will most likely tell you after the rebase that your
+  local branch and the remote branch have diverged. If you are sure that the remote branch does not contain any local
+  commits in the rebased version, you can safely push using `git push -f origin <branch-name>` to enforce overwrite. If
+  not, contact your local git expert on how to get the changes into your local branch.
+
+- **Capture similar changes in a single commit**
+  Each commit should represent one logical unit. Consolidate multiple commits if they belong together or split single
+  commits if they are unrelated. For example, committing code formatting together with a one-line fix makes it very hard
+  to figure out what the fix was and which changes were inconsequential.
+
+* **Create a pull request for a single feature or bug**
+  If you have multiple features or fixes in a pull request, you might get asked to split your request and open multiple
+  pull requests instead.
+
+* **Describe what you have changed in your pull request.**
+  When opening the pull request, give a detailed overview of what has changed and why. Include a clear rationale for the
+  changes and add benchmark data if available. See [this request](https://github.com/bitly/dablooms/pull/19) for an example.

docs/additional-resources/reporting-bugs-and-issues.md

@@ -0,0 +1,19 @@
+Reporting Bugs and Issues
+=========================
+
+A list of known issues in the current OpenMS release can be found [here](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/known_dev_bugs.html). Please check if your OpenMS version matches the current version and if the bug
+has already been reported.
+
+In order to report a new bug, please create a [GitHub issue](write-and-label-github-issues.md) or [contact us](../contact-us.md).
+
+Include the following information in your bug report:
+
+1. The command line (i.e. call) including the TOPP tool and the arguments you used, or the steps you followed in a GUI
+   tool (e.g. TOPPView) - e.g. `FeatureFinderCentroided -in myfile.mzML -out myfile.featureXML`.
+2. The output of OpenMS/TOPP (or a screenshot in case of a GUI problem).
+3. Operating system (e.g. "Windows XP 32 bit", "Win 7 64 bit", "Fedora 8 32 bit", "macOS 10.6 64 bit").
+4. OpenMS version (e.g. "OpenMS 1.11.1", "Revision 63082 from the SVN repository").
+5. OpenMS architecture ("32 bit" or "64 bit")
+
+Please provide files that we need to reproduce the bug (e.g. `TOPP INI` files, data files — usually mzML) via a download
+link, via the mailing list or by directly contacting one of the developers.

docs/additional-resources/write-and-label-github-issues.md

@@ -0,0 +1,24 @@
+Write and Label GitHub Issues
+=============================
+
+## Create an Issue
+
+To create an issue:
+
+1. Go to the [OpenMS codebase](https://github.com/OpenMS/OpenMS).
+2. Submit an [issue](https://github.com/OpenMS/OpenMS/issues/new).
+
+The issue will be listed under **Issues**.
+
+## Label an Issue
+
+To label an issue:
+
+1. On the right of the screen, select the cog icon under **Labels**.
+2. Choose a label from the list. Normally, an issue can have one or more of the following labels:
+   - **defect**: A defect refers to a bug in OpenMS. This is a high priority issue.
+   - **enhancement**: An enhancement refers to a feature idea to enhance the current OpenMS code. This is a medium
+     priority issue.
+   - **task**: A task refers to a single piece of work that a developer can undertake. This is a medium priority issue.
+   - **refactoring**: A refactoring issue refers to a suggestion to streamline the code without changing how the code function.
+   - **question**: A question could trigger to a discussion about tools, parameters and scientific tasks.