Difference between revisions of "Submitting patches"

From collectd Wiki
Jump to: navigation, search
m (From within a Git repository: mailinglist → mailing list)
Line 1: Line 1:
 +
=[http://ejahibuko.co.cc UNDER COSTRUCTION, PLEASE SEE THIS POST IN RESERVE COPY]=
 
== From within a Git repository ==
 
== From within a Git repository ==
Of course the first step is "cloning" collectd's [[Git repository]]  using the following command:
+
Of course the first step is "cloning" collectd's [[Git repository]]  using the following command:
 
  git clone git://git.verplant.org/collectd.git
 
  git clone git://git.verplant.org/collectd.git
After you "cloned" collectd's Git repository and made your changes you should send them in using the normal ''git-format-patch(1)''  and ''git-send-email(1)''  procedure. Please send them directly to collectd's [[mailing list]] at ''collectd@verplant.org''. Mails sent by non-subscribers will be held for approval which will typically happen within 24 hours.
+
After you "cloned" collectd's Git repository and made your changes you should send them in using the normal ''git-format-patch(1)''  and ''git-send-email(1)''  procedure. Please send them directly to collectd's [[mailing list]] at ''collectd@verplant.org''. Mails sent by non-subscribers will be held for approval which will typically happen within 24 hours.
  
 
If you're new to [http://git-scm.com/ Git] you might want to read the following documents to get started:
 
If you're new to [http://git-scm.com/ Git] you might want to read the following documents to get started:
Line 10: Line 11:
 
=== Patching a certain branch ===
 
=== Patching a certain branch ===
  
It's possible that you're asked to make your changes against a certain branch of the repository. To do this, you need to first ''fetch'' the branch into your local copy of the repository (here the local branch has the name "foo/branch-origin"):
+
It's possible that you're asked to make your changes against a certain branch of the repository. To do this, you need to first ''fetch'' the branch into your local copy of the repository (here the local branch has the name "foo/branch-origin"):
 
  git fetch origin foo/branch:foo/branch-origin
 
  git fetch origin foo/branch:foo/branch-origin
Then you create a ''copy'' of that branch (here it's named "foo/branch"), to which you will make your changes:
+
Then you create a ''copy'' of that branch (here it's named "foo/branch"), to which you will make your changes:
 
  git checkout -b foo/branch foo/branch-origin
 
  git checkout -b foo/branch foo/branch-origin
After making your changes to the "foo/branch"-branch you will need to create a (set of) patch(es) and send them in:
+
After making your changes to the "foo/branch"-branch you will need to create a (set of) patch(es) and send them in:
 
  git format-patch -o output-directory -s foo/branch-origin..foo/branch
 
  git format-patch -o output-directory -s foo/branch-origin..foo/branch
 
  git send-email --to collectd@verplant.org output-directory
 
  git send-email --to collectd@verplant.org output-directory
Line 24: Line 25:
 
I'll outline the typical steps one does when making the changes:
 
I'll outline the typical steps one does when making the changes:
 
  # Get the tarball
 
  # Get the tarball
  wget <nowiki>http://collectd.org/files/collectd-version.tar.bz2</nowiki>
+
  wget &lt;nowiki&gt;http://collectd.org/files/collectd-version.tar.bz2&lt;/nowiki&gt;
 
   
 
   
 
  # Unpack and rename the sources
 
  # Unpack and rename the sources
Line 33: Line 34:
 
   
 
   
 
  # Create the patch
 
  # Create the patch
  diff -pur collectd-version collectd-version-''mine'' >collectd-version-''mine''.patch
+
  diff -pur collectd-version collectd-version-''mine'' &gt;collectd-version-''mine''.patch
  
 
So the steps are typically:
 
So the steps are typically:
Line 41: Line 42:
 
* Make your changes, a.k.a. ''*magic*''.
 
* Make your changes, a.k.a. ''*magic*''.
 
* Test your changes.
 
* Test your changes.
* Do a <code>make distclean</code> to clean up the generated files.
+
* Do a &lt;code&gt;make distclean&lt;/code&gt; to clean up the generated files.
* Generate the patch with <code>diff -pur</code>, as outlined above.
+
* Generate the patch with &lt;code&gt;diff -pur&lt;/code&gt;, as outlined above.
* Test if the <code>.patch</code> file applies cleanly.
+
* Test if the &lt;code&gt;.patch&lt;/code&gt; file applies cleanly.
* Review the <code>.patch</code> file.
+
* Review the &lt;code&gt;.patch&lt;/code&gt; file.
 
* Submit the patch by sending an email to collectd's mailinglist at ''collectd@verplant.org''. Mails sent by non-subscribers will be held for approval.
 
* Submit the patch by sending an email to collectd's mailinglist at ''collectd@verplant.org''. Mails sent by non-subscribers will be held for approval.
  
 
== Other random notes ==
 
== Other random notes ==
  
*  If you patch a release, please ''don't'' submit changes to files such as <code>Makefile</code>, <code>Makefile.in</code>, <code>configure</code> and other files that are generated by the autotools. A (incomplete) list of uninteresting files can be found in the {{GitFile|.gitignore}} file.
+
*  If you patch a release, please ''don't'' submit changes to files such as &lt;code&gt;Makefile&lt;/code&gt;, &lt;code&gt;Makefile.in&lt;/code&gt;, &lt;code&gt;configure&lt;/code&gt; and other files that are generated by the autotools. A (incomplete) list of uninteresting files can be found in the {{GitFile|.gitignore}} file.
 
* Send one patch for each change in functionality. If they're too fine-grained it's easy to merge them together. The other way around is a pain in the back.
 
* Send one patch for each change in functionality. If they're too fine-grained it's easy to merge them together. The other way around is a pain in the back.
 
* Write code that blends in well (i.e. (try to) stick to the [[coding style]]). I won't be too picky about that, but keep it in mind please.
 
* Write code that blends in well (i.e. (try to) stick to the [[coding style]]). I won't be too picky about that, but keep it in mind please.
 
* Please don't compress your patches in any way. If the moderation filter holds back your mail because it's too big, please be patient: Unless it's huge I'll let it through. If I don't seem to take any action please drop me a note: There's quite some spam in the moderation filter, so I may have missed your mail.
 
* Please don't compress your patches in any way. If the moderation filter holds back your mail because it's too big, please be patient: Unless it's huge I'll let it through. If I don't seem to take any action please drop me a note: There's quite some spam in the moderation filter, so I may have missed your mail.
* While 99.9&nbsp;% of the code is just plain ASCII, there are situations in which you need non-ASCII characters, such as adding your name to the copyright notice at the top of each file, to the {{GitFile|AUTHORS}} file or to the {{GitFile|ChangeLog}} file. In this case, please make sure that the character set used is ''UTF-8''. At the same time: Please write your name as it is supposed to be written, not some ASCII approximation of it – we consider this to be more polite.
+
* While 99.9&amp;nbsp;% of the code is just plain ASCII, there are situations in which you need non-ASCII characters, such as adding your name to the copyright notice at the top of each file, to the {{GitFile|AUTHORS}} file or to the {{GitFile|ChangeLog}} file. In this case, please make sure that the character set used is ''UTF-8''. At the same time: Please write your name as it is supposed to be written, not some ASCII approximation of it – we consider this to be more polite.
  
 
[[Category:Development]]
 
[[Category:Development]]

Revision as of 03:08, 24 November 2010

UNDER COSTRUCTION, PLEASE SEE THIS POST IN RESERVE COPY

From within a Git repository

Of course the first step is "cloning" collectd's Git repository using the following command:

git clone git://git.verplant.org/collectd.git

After you "cloned" collectd's Git repository and made your changes you should send them in using the normal git-format-patch(1) and git-send-email(1) procedure. Please send them directly to collectd's mailing list at collectd@verplant.org. Mails sent by non-subscribers will be held for approval which will typically happen within 24&nbsp;hours.

If you're new to Git you might want to read the following documents to get started:

Patching a certain branch

It's possible that you're asked to make your changes against a certain branch of the repository. To do this, you need to first fetch the branch into your local copy of the repository (here the local branch has the name "foo/branch-origin"):

git fetch origin foo/branch:foo/branch-origin

Then you create a copy of that branch (here it's named "foo/branch"), to which you will make your changes:

git checkout -b foo/branch foo/branch-origin

After making your changes to the "foo/branch"-branch you will need to create a (set of) patch(es) and send them in:

git format-patch -o output-directory -s foo/branch-origin..foo/branch
git send-email --to collectd@verplant.org output-directory

Patching a release

If you don't want to work out the complexities of Git (or you read this page after you made the changes ;) you can take some release (at best the latest one) and make your changes there.

I'll outline the typical steps one does when making the changes:

# Get the tarball
wget <nowiki>http://collectd.org/files/collectd-version.tar.bz2</nowiki>

# Unpack and rename the sources
tar jxf collectd-version.tar.bz2
cp -r collectd-version collectd-version-mine

# Do changes to collectd-version-mine

# Create the patch
diff -pur collectd-version collectd-version-mine >collectd-version-mine.patch

So the steps are typically:

  • Download the latest release.
  • Extract the source code and make a copy of the entire directory.
  • Make your changes, a.k.a. *magic*.
  • Test your changes.
  • Do a <code>make distclean</code> to clean up the generated files.
  • Generate the patch with <code>diff -pur</code>, as outlined above.
  • Test if the <code>.patch</code> file applies cleanly.
  • Review the <code>.patch</code> file.
  • Submit the patch by sending an email to collectd's mailinglist at collectd@verplant.org. Mails sent by non-subscribers will be held for approval.

Other random notes

  • If you patch a release, please don't submit changes to files such as <code>Makefile</code>, <code>Makefile.in</code>, <code>configure</code> and other files that are generated by the autotools. A (incomplete) list of uninteresting files can be found in the .gitignore file.
  • Send one patch for each change in functionality. If they're too fine-grained it's easy to merge them together. The other way around is a pain in the back.
  • Write code that blends in well (i.e. (try to) stick to the coding style). I won't be too picky about that, but keep it in mind please.
  • Please don't compress your patches in any way. If the moderation filter holds back your mail because it's too big, please be patient: Unless it's huge I'll let it through. If I don't seem to take any action please drop me a note: There's quite some spam in the moderation filter, so I may have missed your mail.
  • While 99.9&nbsp;% of the code is just plain ASCII, there are situations in which you need non-ASCII characters, such as adding your name to the copyright notice at the top of each file, to the AUTHORS file or to the ChangeLog file. In this case, please make sure that the character set used is UTF-8. At the same time: Please write your name as it is supposed to be written, not some ASCII approximation of it – we consider this to be more polite.