Merge pull request 'Add a contribution guide' (!32) from add-a-contribution-guide into main

Reviewed-on: #32
Reviewed-by: Brian Mc Cullough <bmccullough@cacert.org>
Reviewed-by: Dirk Astrath <dirk@cacert.org>

CONTRIBUTING.md

@@ -0,0 +1,196 @@
+# Contributing to the CAcert code base
+
+This short guide will help you to get your contributions into the cacert-webdb
+code base.
+
+## Checking the bug tracker
+
+CAcert tracks bugs in the bug tracker at https://bugs.cacert.org/. Please look
+whether the change you want to contribute addresses any of the issues there.
+The bug tracker is linked from the "Issues" link on
+https://code.cacert.org/cacert/cacert-webdb.
+
+## Clone the repository
+
+You need a local working copy to contribute changes. Get a clone using a git
+client of your choice. The following shell snippets use the official git
+command line client that can be installed from common Linux distribution
+repositories or can be downloaded or installed from [the Git project
+website](https://git-scm.com/downloads).
+
+```shell
+# go to where you usually store your code or projects
+cd ~/projects
+# clone the repository
+git clone https://code.cacert.org/cacert/cacert-webdb.git
+```
+
+## Create a local bugfix branch
+
+Get the latest changes from the original repository before you start
+
+```shell
+# go to your local copy of the cacert-webdb repository
+cd ~/projects/cacert-webdb
+# fetch all recent changes (not needed if you just cloned the repository)
+# -p removes local copies of branches that are no longer available in the
+# main repository
+git fetch --all -p
+```
+
+Create a new bugfix branch based on the origin/main branch. The main branch is
+where all changes are merged before they are deployed in production.
+
+```
+# go to your local copy of the cacert-webdb repository
+cd ~/projects/cacert-webdb
+# create a new branch from the main branch
+git checkout -b the-descriptive-name-for-your-change origin/main
+```
+
+## Edit code / documentation
+
+Make sure that you do the minimal required changes to the code or documentation
+files, this will make life of reviewers easier. Avoid whitespace changes and
+code reformatting that are not related to the lines that you change. Code
+reformatting should be performed in separate branches and pull requests that
+contain no other changes.
+
+Try to keep your changes small and isolated. A pull request (PR) should focus
+on a single purpose.
+
+Code comments should be used to explain the "Why" of code. It does not make
+sense to comment things that are obvious from the code itself:
+
+```php
+// BAD EXAMPLE, don't do this
+// print Hello
+print("Hello");
+```
+
+## Commit your changes
+
+Commit the changes that you made to your local branch. Please provide a
+[meaningful commit message](https://chris.beams.io/posts/git-commit/) and
+reference the bug number from the [Bug tracker](https://bugs.cacert.org/) when
+you contribute to fix any of the issues.
+
+```shell
+git add .
+git commit -m "Fix foo in bla subsystem
+
+This commit does XYZ to address ABC.
+
+Address #<number>"
+```
+
+You may add more commits but please make sure that you only do changes required
+for the specific contribution. Please use new branches for other
+features/bugfixes (see above).
+
+## Contribute your changes
+
+There are two ways to contribute changes. You can either push your branch to
+https://code.cacert.org/cacert/cacert-webdb or you can upload a series of patches to
+the bug tracker. Pushing the changes to https://code.cacert.org/ is the
+preferred variant as it makes life of reviewers easier.
+
+If it took a while to prepare your changes you should rebase your branch on the
+latest changes in the CAcertOrg/cacert-devel release branch:
+
+```shell
+# go to your local copy of the cacert-webdb repository
+cd ~/projects/cacert-webdb
+git fetch --all -p
+git rebase origin/main
+```
+
+You might need to fix merge conflicts in case you changed the same lines as
+another contributor. A introduction to merge conflict handling can be found in
+the [Git Book](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#_basic_merge_conflicts).
+
+Please be aware that all of us are volunteers. It might take a while until we
+find the time to review and merge your changes.
+
+### Create a pull request on code.cacert.org
+
+You need a user account on code.cacert.org to contribute changes. If you don't
+have an account yet send a mail to code-admin@cacert.org and include:
+
+* your full name
+* an email address
+* a desired short username (up to 16 characters)
+* a short introduction about you, if you are not yet known to other members of
+  the software team
+
+An administrator will create an account for you and give you access to the
+repositories. When you have received the welcome mail from the administrator
+you should login to https://code.cacert.org/ and set your password.
+
+Once you logged in using your password you may choose to add OpenID Connect
+authentication to your account. Visit the
+[Security](https://code.cacert.org/user/settings/security) settings of your
+account and click on "Link account" and choose "cacert-oidc". You can then use
+a CAcert client certificate and use the "Sign in with cacert-oidc" option for
+future logins to the code.cacert.org application.
+
+After this onboarding procedure you can push changes to the repository and
+create pull requests.
+
+```shell
+# go to your local copy of the cacert-webdb repository
+cd ~/projects/cacert-webdb
+# push your changes
+git push -u origin the-descriptive-name-for-your-change
+```
+
+The response to the push command will contain a short description and a link to
+create a pull request. Please follow that link or go to
+https://code.cacert.org/cacert/cacert-webdb/pulls to create a new pull request
+from your branch to the main branch.
+
+The code.cacert.org system will suggest a short description based on your
+commit messages, you should add more information if you think that reviewers
+will need some context to understand your pull requests' intent.
+
+### Submit a series of patches for the bug tracker
+
+If you have reasons not to use the pull request workflow you may create a
+series of patches for your changes. Please be aware that this makes reviews
+harder and may delay merging the changes.
+
+To create a series of patches use the following:
+
+```shell
+# go to your local copy of the cacert-webdb repository
+cd ~/projects/cacert-webdb
+# fetch the latest changes if it has been a while
+git fetch --all -p
+# create a patch series and write the patches to the /tmp/ directory
+git format-patch -o /tmp origin/main..the-descriptive-name-for-your-change
+```
+
+The git format-patch command will output the patch file names, similar to this:
+
+```text
+/tmp/0001-Change-the-files-for-me.patch
+/tmp/0002-Update-the-documentation.patch
+```
+
+To submit this open the corresponding issue in [the bug
+tracker](https://bugs.cacert.org/) and attach the patch files to the bug
+report. Please add a descriptive comment to help reviewers understand what you
+have changed.
+
+## What next?
+
+Once you have submitted your pull request or patch files you need to wait for
+reviews. If your changes look ok they will be merged into the main branch.
+Deployments to the production system are usually done close to the merges and
+will be marked using git tags.
+
+If reviewers ask you for changes to your pull requests please use your local
+copy of the cacert-webdb code, add new commits to your branch and push them as
+described above. The git format-patch workflow is a bit harder. You will need
+to create a new patch series based on what you have submitted before and will
+need to attach the new patch(es) to the bug tracker.