= 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 link:https://github.com/OpenSCAP/openscap/issues[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 link:https://github.com/OpenSCAP/openscap[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:

[source,bash]

----

$ 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:

[source,bash]

----

$ 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 link:versioning.adoc[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

link:https://www.redhat.com/mailman/listinfo/open-scap-list[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:

[source,bash]

----

$ 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:

[source,bash]

----

# 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

link:http://chris.beams.io/posts/git-commit/[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

link:https://help.github.com/articles/closing-issues-via-commit-messages/[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

link:testing.adoc[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:

[source,bash]

----

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

[source,bash]

----

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

[source,bash]

----

# 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 link:https://help.github.com/articles/creating-a-pull-request/[create] a

new pull request. You can create the pull request on the OpenSCAP's

link:https://github.com/OpenSCAP/openscap/pulls[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:

 . Add a new commit,

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

[source,bash]

----

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

[source,bash]

----

$ 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:

[source,bash]

----

# 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

----