AutoQA Patch Process

Newcomers

If you never tinkered with AutoQA and you want to make some simple adjustment and send us the patch, continue reading this section.

Getting started

Before you do anything else ... you'll need to install git.

yum install git

The basics

Checkout The Code

It's always easier if you start from a fresh git clone, as git makes it very easy to do patches. You won't have to run "patch" manually and stuff like that, nor will you have to maintain a separate tree.

git clone git://git.fedorahosted.org/autoqa.git

Keep In Sync

If you want to update your checkout to the latest git source, from any branch:

git fetch origin
git rebase origin/master

What Changed?

Now, make your changes. To see the differences you've made since last commit:

git diff HEAD

At any time when you want to stay up to date with what's going on in the main repo you can do the fetch/rebase step as many times as you want. This makes all your changes be modified as if they were applied to the latest on the remote branch.

Did I break anything?

Please make sure your changes didn't cause any regressions. Run the tests before every patch submission or commit:

make test

Oops, How do I Revert?

To revert your changes:

git checkout -f                     # All changes
git checkout -f autoqa.spec         # A specific file

Advanced topics

Patch submission

Once you have the checkout working like you want, you can generate a list of patches and submit for review to autoqa-devel@lists.fedorahosted.org. The procedure is detailed below.

1. First, be sure to commit all the changes locally:

   git commit -a 

2. Next, generate a list of patches between your local checkout and a remove branch called origin/master, type:

   git format-patch origin/master

   This will output a list of one or more patches that can be downloaded and applied by developers using the command git am.
3. Now, write a high level summary of your changes:

   cat <<EOF> msg
   Subject: My favorite patches
    
   Hello,
    
   Included are several packages which implement feature X and have been thoroughly tested.
   
   Thanks!
   EOF

4. Finally, send the patches along with the descriptive summary to autoqa-devel@lists.fedorahosted.org for review:

   yum install git-email
   git send-email --no-chain-reply-to --quiet --to autoqa-devel@lists.fedorahosted.org msg *.patch

Named Branch

If you are developing a feature or working on a rather large patchset for AutoQA, you are recommended to create a named branch to work from. This makes patch submission and merging easier for the AutoQA maintainers.

To create and share a named branch called myusername ...

1. Create a new branch locally, based on current branch (master)

   git checkout -b myusername

2. Now, share your branch by pushing it into the remote repo

   git push origin myusername

3. Finally, configure the local repo to merge with the remote so git pull works

   git branch --set-upstream myusername origin/myusername

Private Branch

If you don't have, or want, commit access to the autoqa git repository to host your private repo, you may host your repository on fedorapeople.org. Read the instructions for information on setting up git hosting on fedorapeople.org.

AutoQA developers

If you are already an AutoQA developer with write access to autoqa.git, there are a few guidelines to follow:

Committing to master branch

1. Trivial commits that can hardly influence other people's code don't have to be sent as patches and don't have to be announced on the mailing list.
   • Examples: adding printouts for verbose mode; changing comments
2. Smaller commits that are likely to have small to zero impact on AutoQA core functionality but could be interesting for other developers don't have to sent as patches, but should be announced.
   • Append the diff to your message and add a note saying it's been already committed, or place a link to the commitdiff in your message.
   • Examples: fixing a bug in a single test; substantially improving test output format; adding helper function to autoqa library; changing Makefile or spec file
3. Large commits that influence AutoQA core functionality should be sent as patches and you should wait for their review.
   • If the change is too large for sending as a textual diff, push your changes to a remote branch and link to it in your message.
   • If your patch is approved by at least one other AutoQA developer, you can push to master. If you're not in rush you can of course wait for more opinions.
   • Examples: changing core library; changing main autoqa script; changing the watchers
4. When merging your branch with the master branch:
   1. If your branch adds a single patch or a small number of self-contained patches with reasonable commit messages, you can merge with master.
      • Rebase first, if applicable (the code is in your private branch or nobody based his work on it).
   2. If your branch consists of large number of 'development-style' commits (non-descriptive commit messages, the commits sometimes break code elsewhere just to fix it later with another commit), squash the merge and push the change as a single commit. Provide a fully descriptive commit message.
5. Use your common sense and adjust the guidelines above according to your current situation and your experience. Nothing is cast in stone.
6. If you're not sure, just ask.

References

• http://www.kernel.org/pub/software/scm/git/docs/user-manual.html