6.8 KiB
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.
# 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
# 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:
// 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 and reference the bug number from the Bug tracker when you contribute to fix any of the issues.
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:
# 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.
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.
# 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:
# 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:
/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 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.