Skip to content

Latest commit

 

History

History
224 lines (185 loc) · 9.18 KB

contribute.adoc

File metadata and controls

224 lines (185 loc) · 9.18 KB
Raw

How to Contribute to OpenSCAP

This document is meant for new OpenSCAP contributors and it describes how to contribute to the OpenSCAP project. Let’s suppose that you already have an active Github’s account with a user name adam and you want to fix one of the issue from the tracker. Let’s say that you want to fix the issue with number 455 and the fix will go into the maint-1.2 branch.

Note
 This guide also applies for adding a new feature, the process is the same as for fixing an issue described below.

Fork and setup the OpenSCAP repository

Before you start working on a fix it’s a good practice to leave a comment in the issue that you work on the fix so other contributors know that the fix is in progress. Next thing you have to do is to fork the OpenSCAP repository. You can do that by pressing the 'Fork' button in the top-right corner on the Github’s OpenSCAP page. It will create a copy of the original repository which you can use for proposing changes. Then you can clone your forked repository:

$ git clone git@github.com:adam/openscap.git

Sometimes you will need to update your forked repository with the latest upstream changes. To be able to do so you need to add a remote (we will name it upstream) which will track the upstream OpenSCAP repository:

$ cd openscap/
# add remote name 'upstream' to refer to the upstream's repository
$ git remote add upstream git@github.com:OpenSCAP/openscap.git
Note
 In the code snippets, lines starting with # are comments and lines starting with $ are commands.

Choose the right branch

Before you start working on the fix it’s necessary to determine which branch the fix will go into. If you are not familiar with the OpenSCAP’s branches or versions yet please have a look at the versioning document. Be aware that the fact that an issue description says that the fix should go to the maint-1.2 branch doesn’t have to be true. It’s a good practice to investigate the correct branch first or ask experienced developers on our FreeNode IRC channel called #openscap or mailing list.

Note
 The default branch of the openscap repository is set to the maint-1.2.

Once you have forked the repository and decided that the fix will go into the maint-1.2 branch you can create a new branch from it, which we will call fix_455, where you can work on the fix. Remember that the name of the new branch will appear in the commit message when your fix is merged so choose the name wisely:

$ git checkout maint-1.2
# create a new branch
$ git checkout -b fix_455

On the other hand, if you decided that the fix will go into the master branch you have to switch to this branch first before creating a new one:

# create a new local branch to track the remote master branch
$ git checkout -b master remotes/origin/master
# and now create a new branch from the master branch which will contain your fix
$ git checkout -b fix_455

Fix the issue

Note
 OpenSCAP is licensed under LGPL v2.1. Any fixes or improvements must be licensed under the same license to be included. Check the COPYING file in the repository for more details.

Now you can work on the fix. Try to create small commits which can be easily reviewed and make self-explaining commit messages. The How to Write a Git Commit Message article could help you with that. Nobody will review a pull request which contains a four thousand new lines of code.

Note
 Since you’re fixing issue number 455 make sure that your commit message contain a keyword which will close the issue automatically when your pull request is merged.

Let’s say that you’ve fixed the issue, made a few commits to your local fix_455 branch and you think it’s ready to be reviewed by other contributors. Before you push your local changes to your remote forked repository it’s necessary to check if your changes will be applicable and won’t be in a conflict with some work that other contributors could have published while you were working on the fix.

Optional: Write an automated test for your code

There is a big chance that the code you’ve fixed or the code that you’ve added has no test coverage. We encourage you to write a new test or extend the existing one to cover the changes/additions to OpenSCAP that you have made. It is not mandatory, so reviewer will not require you to write a test, but keep in mind that providing a test might uncover some unexpected issues with the code. We also run these tests on every pull request so adding a test for your fix or new feature might prevent someone from breaking it in the future. If you decided to add a test please see our guide for writing and running tests.

Rebase before pull request

If some other contributor pushed some code to the maint-1.2 branch while you were working on the fix and if there would be a conflict between your changes then it might be necessary to fetch those changes and rebase your fix on top of them. First you need to make sure that your local maint-1.2 branch is up-to date:

# checkout to branch 'maint-1.2' in your local forked repository
$ git checkout maint-1.2
# download and apply any upstream changes to your local maint-1.2 branch
$ git pull upstream maint-1.2
# now you can optionally also push these changes to your fork on Github (recommended)
$ git push origin maint-1.2

Now you can go back to your local branch with the fix and try to rebase your changes on top of your local updated maint-1.2 branch:

# checkout back to your branch with the fix
$ git checkout fix_455
# rebase your changes on the top of the updated maint-1.2 branch
$ git rebase maint-1.2

If there are no conflicts then you can push your branch with the fix to your remote forked repository:

# push your changes to your remote forked repository (also see the note below)
$ git push origin fix_455
Note
 The previous git push command will not work if you’ve already pushed the branch to your remote repository. If this is the case, but you made some new changes/updates and you want to push them into the fix_455 branch then append the --force after the git push command. Be aware that it will rewrite your fix_455 branch in your remote forked repository.

Create a new pull request

Once you have pushed your local fix_455 branch to your remote forked repository you can create a new pull request. You can create the pull request on the OpenSCAP’s github page when you click on the 'Pull requests' in the right menu then you see the green 'New pull request' button. In the branch menu choose the branch that contains your fix. That is the fix_455 branch and also don’t forget to set maint-1.2 as the base branch. The base branch is the one that your fix_455 will be compared to. If there are no conflicts add some description and hit the 'Create pull request' button.

Developers and contributor that watch the repository should now receive an email about a new pull request. They will review your code and probably leave you some comments. If there are any you should get back to your code and make the changes.

Make changes in the submitted pull request

After the review is done and one or more experienced developers is complaining about your code you have to do some changes. There are two ways to change your code in a submitted pull request:

  1. Add a new commit,

  2. or edit existing commits.

Add a new commit

Adding a new commit is easy and it is a good option if you have to add something new like a function or a new module.

Edit existing commits

If you just need to fix something (for example a typo) you need to go back to the commit where the change is needed and use commit’s --amend option to change the commit. You can use the following steps to do that:

# show all the commits in your fix_455 branch
$ git rebase -i maint-1.2
# replace 'pick' with 'e' at the line with commit(s) you'd like to edit
# make your changes
# vim my_source_file.c
# commit your new changes
$ git commit --amend
# move to the next commit which you selected for editing using 'e' in the
# 'git rebase' command
$ git rebase --continue

When you are finished with editing commits you can force push all the changes into your remote repository to update it with your latest edits. The pull request will be updated automatically too:

$ git push --force origin fix_455

Closing the pull request

Once the pull request has been merged to upstream’s branch the pull request will be closed automatically. The issue will be also closed if you used the right keyword in the commit message. Now you can delete your fix_455 branch:

# detele the fix_455 branch locally
$ git branch -d fix_455
# optionally also delete the fix_455 branch from your remote forked repository
$ git push origin --delete fix_455