diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2c006bb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,189 @@ +# 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 # +``` + +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.