cacert-webdb/CONTRIBUTING.md

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