From Fedora Project Wiki

Revision as of 17:26, 28 June 2011 by Jlaska (talk | contribs) (Keep references at the bottom)

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 Package-x-generic-16.pnggit.

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), make a single diff of your branch and the master and then commit the whole 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.

Using stable branch

As opposed to master branch used for main development, the stable branch is used for producing stable releases. Only code that is deemed stable and desired for the next AutoQA released is cherry-picked from the master branch. This is the workflow:

  1. When a new major/minor release is to be released, the code is pulled from master branch to stable branch (up to the commit that should represent the tip of the new release). A new tag is created and a new release is published.
  2. When a revision (bugfix) release is to be released, the bugfix is first committed to master and then it is pulled into stable branch (with small code adjustments if necessary). After all the required bugfixes are present in the stable branch, the code is tagged and a new release is published.

References