189 lines
6.8 KiB
Markdown
189 lines
6.8 KiB
Markdown
# 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.
|
|
|
|
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.
|