From Fedora Project Wiki

(we don't use stable branch anymore)
 
(20 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This page outlines a few tips to get started contributing patches to the beaker project.  This page borrows '''heavily''' from [https://fedorahosted.org/beaker/wiki/PatchProcess beaker Patch Process].
= Newcomers =


= Checkout The Code =
If you never tinkered with [[AutoQA]] and you want to make some simple adjustment and send us the patch, continue reading this section.


It's always easier if you start from a git checkout, 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.
== Getting started ==


<pre>git clone git://git.fedorahosted.org/autoqa.git </pre>
Before you do anything else ... you'll need to install {{package|git}}.


= Keeping In Sync =
<pre>
yum install git
</pre>
 
== 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.
 
<pre>
git clone git://git.fedorahosted.org/autoqa.git
</pre>
 
=== Keep In Sync ===


If you want to update your checkout to the latest git source, from any branch:
If you want to update your checkout to the latest git source, from any branch:
Line 16: Line 30:
</pre>
</pre>


= What Changed? =
=== What Changed? ===


Now, make your changes. To see the differences you've made since last commit:
Now, make your changes. To see the differences you've made since last commit:
Line 22: Line 36:
<pre>git diff HEAD</pre>
<pre>git diff HEAD</pre>


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
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.
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:
 
<pre>make test</pre>


= Oops, How to I Revert? =
=== Oops, How do I Revert? ===


To revert your changes:
To revert your changes:
<pre>
<pre>
git checkout -f                    # All changes
git checkout -f                    # All changes
git checkout -f Medusa/setup.py    # A specific file
git checkout -f autoqa.spec        # A specific file
</pre>
</pre>


= Submitting Patches For Review =
== Advanced topics ==


Once you have the checkout working like you want, generate a list of patches and submit for review to bautoqa-devel@lists.fedorahosted.org. 
=== Patch submission ===


Record all the changes:
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.


<pre> git commit -a </pre>
<ol>
<li> First, be sure to commit all the changes locally:
<pre>git commit -a </pre>
<li> Next, generate a list of patches between your local checkout and a remove branch called ''origin/master'', type:
<pre>git format-patch origin/master</pre> This will output a list of one or more patches that can be downloaded and applied by developers using the command {{command|git am}}.
<li> Now, write a high level summary of your changes:
<pre>cat <<EOF> msg
Subject: My favorite patches
Hello,
Included are several packages which implement feature X and have been thoroughly tested.


Generate a list of patches between your local checkout and a remove branch called ''origin/master'', type:
Thanks!
EOF</pre>
<li> Finally, send the patches along with the descriptive summary to ''autoqa-devel@lists.fedorahosted.org'' for review:
<pre>yum install git-email
git send-email --no-chain-reply-to --quiet --to autoqa-devel@lists.fedorahosted.org msg *.patch</pre>
</ol>


<pre>/usr/libexec/git-core/git-format-patch origin/master</pre>
=== Named Branch ===


This will output a list of one or more patches that can be downloaded and applied by developers with "git am".
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.


Now, write a high level summary of your changes:
To create and share a named branch called ''myusername'' ...


<pre>
<ol>
cat <<EOF> msg
<li> Create a new branch locally, based on current branch (master)
Subject: My favorite patches
<pre>git checkout -b myusername</pre>
<li> Now, share your branch by pushing it into the remote repo
<pre>git push origin myusername</pre>
<li> Finally, configure the local repo to merge with the remote so ''git pull'' works
<pre>git branch --set-upstream myusername origin/myusername</pre>
</ol>


Hello,
=== Private Branch ===


Included are several packages which implement feature X and have been thoroughly tested.
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 [[Infrastructure/fedorapeople.org#BETA_git_hosting_support|instructions]] for information on setting up git hosting on fedorapeople.org.


Thanks!
= AutoQA developers =
EOF
</pre>


Finally, send these patches to ''autoqa-devel@lists.fedorahosted.org'' for review:
If you are already an AutoQA developer with write access to [http://git.fedorahosted.org/git/?p=autoqa.git autoqa.git], there are a few guidelines to follow:


<pre>
== Committing to master branch ==
yum install git-email.noarch
/usr/libexec/git-core/git-send-email --no-chain-reply-to --quiet --to autoqa-devel@lists.fedorahosted.org msg *.patch
</pre>


# 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
# 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
# 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
# When merging your branch with the master branch:
## 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).
## 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), [http://kparal.wordpress.com/2011/07/04/git-tip-of-the-day-squashing-merges/ squash the merge] and push the change as a single commit. Provide a fully descriptive commit message.
# Use your common sense and adjust the guidelines above according to your current situation and your experience. Nothing is cast in stone.
# If you're not sure, just ask.


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


[[Category:AutoQA]]
[[Category:AutoQA]]

Latest revision as of 08:15, 5 September 2011

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), 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