Contributing

Differences between revisions 2 and 3
Revision 2 as of 2007-05-24 09:01:53
Size: 24
Editor: p1033-ipbf37marunouchi
Comment:
Revision 3 as of 2007-05-25 18:32:47
Size: 12274
Editor: p1033-ipbf37marunouchi
Comment: Initial Draft
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
#REDIRECT MOTU/Hopeful = Contributing to Universe =

== Why Contribute to MOTU ==

 * [:MOTU:MOTU] contributions are considered when applying for [:NewMemberHowto:Membership]
 * It will make your system work better
 * It's fun!


== First Steps ==

 * [https://launchpad.net/+login Register] in LaunchPad
 * Become familar with Ubuntu [:HelpingWithBugs:Bug Management] Procedures
 * Review some of the [:MOTU/Documentation:Documentation] available
 * If you want an introduction to the community, investigate [:MOTU/Mentoring:Mentoring]
 * Consider joining #ubuntu-motu on [https://help.ubuntu.com/community/InternetRelayChat IRC]

== Things to Do ==

Below please find a short list of ways in which help is most appreciated. Feel free to select activities from any of the below, including combinations (e.g. fixing a bug, and submitting a new revision).

=== Preparing Patches ===

Prerequisites:
 * Join the [https://launchpad.net/~bugsquad BugSquad] Team

There are a lot of bugs in Universe, and many of them have fairly simple fixes, and some have more complex fixes. If you understand a bug well enough to fix it, please post a patch or explanation to the bug. If you start work on a bug, be sure to set the Status to "In Progress" and assign yourself.

If the bug requires a patch to the sources, review the [:MOTU/School/PatchingSources:Patching Guide] to determine how to create a patch. If there is no patch system, [:Bugs/HowToFix:these instructions] may help you to generate the necessary patch.

If a bug requires a patch to the packaging (under debian/, but not under debian/patches), a patch should only be generated against the debian/ directory, as follows:


{{{
$ cp -a debian debian.old
}}}
Make any required changes in the debian/ directory
{{{
$ diff -urN debian.old debian > ../packagename.debian.patch
$ rm -r debian.old
}}}

After generating a patch, please be sure to:

 1. Attach the patch to the bug

 1. Add the "patch" tag to the bug

 1. Set status to "Confirmed" and assign to "Nobody"

 1. Check to see if the bug applies to the Debian package. If so:
  a. If one does not already exist, open a bug in Debian & attach the patch (use Tags: patch(
  a. If there is a bug, verify it is linked in launchpad & forward the patch to the BTS

 1. Check to see if the bug applies to upstream VCS, If so:
  a. Prepare a minimal testcase demonstrating the bug
  a. Send the testcase and patch upstream for review (use the upstream bugtracker, if available)
  a. Either link the upstream bug in launchpad, or leave the URL in a comment
  a. Update the Debian bug with the upstream bug information

=== Preparing New Revisions ===

Prerequisites:
 * Join the [https://launchpad.net/~bugsquad BugSquad] Team
 * Sign the [https://launchpad.net/codeofconduct Code of Conduct]
 * Install {{{devscripts}}} and associated suggested packages

Each upload of a package to the archive represents a new revision, and carries a unique changelog entry. The preparation of new revisions represents the end product of the majority of MOTU effort, and is a wonderful way to learn about packaging, as you will be exposed to many different packaging styles.

Before starting, search for bugs that can be closed with the new revision. When selecting bugs, limit yourself to those for which you understand the solution or the patch and from which you believe the majority of users would benefit. Good sources of bugs and patches are:

 1. The package bugs page in launchpad {{{ https;//bugs.launchpad.net/ubuntu/+source/packagename }}}
 1. The package bugs page in the BTS {{{ http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=packagename }}}
 1. After a test build, the output of any of the package analysis commands:

{{{
$ linda -v -f long -t E,I,W,X packagename_version-revision_source.changes
$ linda -v -f long -t E,I,W,X packagename_version-revision_arch.changes
$ lintian -iIv packagename_version-revision_source.changes
$ lintian -iIv packagename_version-revision_arch.changes
}}}

Set all the bugs you intend to fix to "In-Progress" and assign yourself.

Collect and unpack the sources

To get Ubuntu Sources for the release you are currently running, use:
{{{
apt-get source srcpackagename
}}}

If you need sources from another release, try one of:
{{{
https://launchpad.net/ubuntu/+source/packagename
http://packages.qa.debian.org/
}}}

Note that if you take sources from Debian, you will have to insert the changelog entries from Ubuntu to ensure an accurate record of change in the released Ubuntu revision. See the [:MOTU/Packages/Merging:Documentation] on merging for more details.

Apply all the necessary fixes to the package. For changes to the source, create a patch as above, excepting that if there is no patch system, the changes should be applied directly, and no patch extracted. For changes to the packaging, the changes should be applied directly, with the exception that debian/changelog should not be changed manually.

Update the changelog with
{{{
dch -i
}}}

Add a line to the changelog for each change you make to the package. For any that close launchpad bugs, end the line with "(LP: #bugnumber)". For any that close Debian bugs, end the line with "(Debian: #bugnumber)". If a fix closes both, only include the LP entry.

If you are not running the current development environment on your development machine, be careful to ensure that the distribution in the changelog for your revision matches the current development environment, rather than the distribution installed on your development machine.

Prepare a source build with
{{{
debuild -S
}}}

If you encounter errors at this point, likely causes are that your GPG key configuration is not configured correctly or that you do not have the necessary packages installed to complete the clean rule in debian/rules. Be sure to set DEBEMAIL, and install any packages you may need to properly ensure that all patches have been unapplied.

Build the package with [https://help.ubuntu.com/community/SbuildLVMHowto sbuild] or [:PbuilderHowto:pbuilder]

Check that your new revision
 * Has your preferred launchpad email address in Changed-By: in the source.changes file
 * Lists the intended distribution in the source.changes file
 * Has an Ubuntu version number
 * Has an Ubuntu maintainer
 * Installs cleanly in the current development environment
 * Works in the current development environment
 * Addresses the issues listed in the changelog

You may need to make additional changes, if you are not happy with the results of your tests. This may be made directly, but if you make a mistake, you can also use the following to restore the state to your last source build.

{{{
$ rm -r packagename_version
$ dpkg-source -x packagename_version-newrevision.dsc
}}}

If your revision is an update to the Ubuntu repositories, prepare a debdiff for the new candidate revision with:

{{{
$ debdiff packagename_version-revision.dsc packagename_version-newrevision.dsc > packagename_version-newrevision.debdiff
}}}

If your revision is a merge from Debian, prepare a debdiff for the new candidate revision with:

{{{
$ debdiff packagename_version-debianrevision.dsc packagename_version-newrevision.dsc > packagename_version-newrevision.debdiff
}}}

If your revision is a new upstream version, prepare an interdiff with

{{{
interdiff -z packagename_version-revision.diff.gz packagename_newversion-newrevision.diff.gz > packagename_version-newrevision.interdiff
}}}

Review your differences file to ensure that all changes are intentional. If there are unexpected changes, consider removing them from the patch, either using {{{filterdiff}}} or manually. If you are uncertain about a specific change, seek advice from #ubuntu-motu or your [:MOTU/Mentoring:Mentor].

Test your patch. Debdiff patches are best tested with:

{{{
$ rm -r packagename_version
$ dpkg-source -x packagename_version-revision.dsc
$ cd packagename_version
$ patch -p1 ../packagename_version-newrevision.debdiff
}}}

This should generate no rejections or fuzz

Interdiff patches are best tested with

{{{
$ combinediff -z packagename_version-revision.diff.gz packagename_version-newrevision.interdiff > test.diff
$ interdiff -z test.diff packagename_newversion-newrevision.diff.gz
$ rm test.diff
}}}

This should generate no output

If you are completely satisfied, request sponsorship for your new revision.

If your new revision required the generation of an interdiff, rebuild the sources with {{{ debuils -S -sa }}} and upload to [:MOTU/Packages/REVU:REVU]. Note that you must first belong to the [https://launchpad.net/~ubuntu-universe-contributors REVU Upload] Team.

If only one launchpad bug will closed, attach your diff to that bug.
If several launchpad bugs will be closed, open a new bug entitled "Candidate revision packagename_version-revision, and include your changelog entry in the bug description. Attach your diff to this new bug.
If your revision required an interdiff, be sure to include the REVU entry URL in your comment.

Set the bug to Status "Confirmed". Assign to "Nobody". Subscribe the {{{ubuntu-universe-sponsors}}} team to add your bug to the [:MOTU/Sponsorship/SponsorsQueue:Sponsorship Queue].

Once the revision has been uploaded, check {{{https://launchpad.net/~<your LP ID>/+packages}}} for the status of the autobuilders. Once all builds are complete, set the status of the bug to "Fix Released", and add a comment that it built on all architectures. If the build fails, prepare another revision to fix the build, upload that debdiff to the same bug, reset the Status and Assignment for the bug, and resubscribe {{{ubuntu-universe-sponsors}}}.

While you are waiting, review the bugs that will be closed, to make sure that any that apply to Debian have Debian bugs open, and that any related Debian bugs have patches (you may need to extract individual patches from your diff to send to Debian - see Preparing Patches for hints).

If your new revision closes several launchpad bugs, also remember to adjust the status of all the bugs to be closed.

=== Preparing New Packages ===

Prerequisites:
 * Join the [https://launchpad.net/~bugsquad BugSquad] Team
 * Sign the [https://launchpad.net/codeofconduct Code of Conduct]
 * Join the [https://launchpad.net/~ubuntu-universe-contributors REVU Upload] Team
 * Become familiar with the [https://help.ubuntu.com/6.10/ubuntu/packagingguide/C/index.html Packaging Guide]

Procedure:
 * Find or report a [https://bugs.launchpad.net/ubuntu/+bugs?field.tag=needs-packaging Needs Packaging] Bug
 * Set the Status to "In Progress" and assign yourself
 * Create a new Package (Some [:MOTU/Packages/Packaging/Tips:Tips] are available)
 * Verify that packagename_version-revision.diff.gz does not change anything outside debian/
 * Make sure you have an Ubuntu version and Ubuntu Maintainer
 * Build the package with [:PbuilderHowto:pbuilder] or [https://help.ubuntu.com/community/SbuildLVMHowto sbuild]
 * Run the lintian and linda tests to make sure there are no obvious problems
 * Review the [:MOTU/Packages/CommonPackagingMistakes:Common Mistakes] to be safe
 * Check the [:MOTU/Packages/Reviewing:Reviewing Guidelines] to catch things before your reviewers have a chance
 * Upload the package to [:MOTU/Packages/REVU:REVU]
 * Add the REVU upload URL to the bug
 * You may, if you wish, announce your upload to #ubuntu-motu not more than once per day
 * Once the package is uploaded, set the bug Status to "Fix Committed"
 * Once the package is approved and distributed in the archives, set the bug Status to "Fix Released"
 * Contact the [http://utnubu.alioth.debian.org/ Utnubu Team] to get your package into Debian

=== Other Work ===

Other activities are be listed on the [:MOTU/TODO:MOTU Task List]. Check there if you run out of things to do above, or would just like some variety.

If you've contributed a lot over at least two release cycles, and a couple members of ubuntu-dev have suggested you should, please consider [:MOTU/Hopeful/Recruitment:applying] to join the [:MOTU:MOTU] team.

----
["CategoryMOTU"]

Contributing to Universe

Why Contribute to MOTU

  • [:MOTU:MOTU] contributions are considered when applying for [:NewMemberHowto:Membership]

  • It will make your system work better
  • It's fun!

First Steps

Things to Do

Below please find a short list of ways in which help is most appreciated. Feel free to select activities from any of the below, including combinations (e.g. fixing a bug, and submitting a new revision).

Preparing Patches

Prerequisites:

There are a lot of bugs in Universe, and many of them have fairly simple fixes, and some have more complex fixes. If you understand a bug well enough to fix it, please post a patch or explanation to the bug. If you start work on a bug, be sure to set the Status to "In Progress" and assign yourself.

If the bug requires a patch to the sources, review the [:MOTU/School/PatchingSources:Patching Guide] to determine how to create a patch. If there is no patch system, [:Bugs/HowToFix:these instructions] may help you to generate the necessary patch.

If a bug requires a patch to the packaging (under debian/, but not under debian/patches), a patch should only be generated against the debian/ directory, as follows:

$ cp -a debian debian.old

Make any required changes in the debian/ directory

$ diff -urN debian.old debian > ../packagename.debian.patch
$ rm -r debian.old

After generating a patch, please be sure to:

  1. Attach the patch to the bug
  2. Add the "patch" tag to the bug
  3. Set status to "Confirmed" and assign to "Nobody"
  4. Check to see if the bug applies to the Debian package. If so:
    1. If one does not already exist, open a bug in Debian & attach the patch (use Tags: patch(

    2. If there is a bug, verify it is linked in launchpad & forward the patch to the BTS

  5. Check to see if the bug applies to upstream VCS, If so:
    1. Prepare a minimal testcase demonstrating the bug
    2. Send the testcase and patch upstream for review (use the upstream bugtracker, if available)
    3. Either link the upstream bug in launchpad, or leave the URL in a comment
    4. Update the Debian bug with the upstream bug information

Preparing New Revisions

Prerequisites:

Each upload of a package to the archive represents a new revision, and carries a unique changelog entry. The preparation of new revisions represents the end product of the majority of MOTU effort, and is a wonderful way to learn about packaging, as you will be exposed to many different packaging styles.

Before starting, search for bugs that can be closed with the new revision. When selecting bugs, limit yourself to those for which you understand the solution or the patch and from which you believe the majority of users would benefit. Good sources of bugs and patches are:

  1. The package bugs page in launchpad  https;//bugs.launchpad.net/ubuntu/+source/packagename 

  2. The package bugs page in the BTS  http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=packagename 

  3. After a test build, the output of any of the package analysis commands:

$ linda -v -f long -t E,I,W,X packagename_version-revision_source.changes
$ linda -v -f long -t E,I,W,X packagename_version-revision_arch.changes
$ lintian -iIv packagename_version-revision_source.changes
$ lintian -iIv packagename_version-revision_arch.changes

Set all the bugs you intend to fix to "In-Progress" and assign yourself.

Collect and unpack the sources

To get Ubuntu Sources for the release you are currently running, use:

apt-get source srcpackagename

If you need sources from another release, try one of:

https://launchpad.net/ubuntu/+source/packagename
http://packages.qa.debian.org/

Note that if you take sources from Debian, you will have to insert the changelog entries from Ubuntu to ensure an accurate record of change in the released Ubuntu revision. See the [:MOTU/Packages/Merging:Documentation] on merging for more details.

Apply all the necessary fixes to the package. For changes to the source, create a patch as above, excepting that if there is no patch system, the changes should be applied directly, and no patch extracted. For changes to the packaging, the changes should be applied directly, with the exception that debian/changelog should not be changed manually.

Update the changelog with

dch -i

Add a line to the changelog for each change you make to the package. For any that close launchpad bugs, end the line with "(LP: #bugnumber)". For any that close Debian bugs, end the line with "(Debian: #bugnumber)". If a fix closes both, only include the LP entry.

If you are not running the current development environment on your development machine, be careful to ensure that the distribution in the changelog for your revision matches the current development environment, rather than the distribution installed on your development machine.

Prepare a source build with

debuild -S

If you encounter errors at this point, likely causes are that your GPG key configuration is not configured correctly or that you do not have the necessary packages installed to complete the clean rule in debian/rules. Be sure to set DEBEMAIL, and install any packages you may need to properly ensure that all patches have been unapplied.

Build the package with [https://help.ubuntu.com/community/SbuildLVMHowto sbuild] or [:PbuilderHowto:pbuilder]

Check that your new revision

  • Has your preferred launchpad email address in Changed-By: in the source.changes file
  • Lists the intended distribution in the source.changes file
  • Has an Ubuntu version number
  • Has an Ubuntu maintainer
  • Installs cleanly in the current development environment
  • Works in the current development environment
  • Addresses the issues listed in the changelog

You may need to make additional changes, if you are not happy with the results of your tests. This may be made directly, but if you make a mistake, you can also use the following to restore the state to your last source build.

$ rm -r packagename_version
$ dpkg-source -x packagename_version-newrevision.dsc

If your revision is an update to the Ubuntu repositories, prepare a debdiff for the new candidate revision with:

$ debdiff packagename_version-revision.dsc packagename_version-newrevision.dsc > packagename_version-newrevision.debdiff

If your revision is a merge from Debian, prepare a debdiff for the new candidate revision with:

$ debdiff packagename_version-debianrevision.dsc packagename_version-newrevision.dsc > packagename_version-newrevision.debdiff

If your revision is a new upstream version, prepare an interdiff with

interdiff -z packagename_version-revision.diff.gz packagename_newversion-newrevision.diff.gz > packagename_version-newrevision.interdiff

Review your differences file to ensure that all changes are intentional. If there are unexpected changes, consider removing them from the patch, either using filterdiff or manually. If you are uncertain about a specific change, seek advice from #ubuntu-motu or your [:MOTU/Mentoring:Mentor].

Test your patch. Debdiff patches are best tested with:

$ rm -r packagename_version
$ dpkg-source -x packagename_version-revision.dsc
$ cd packagename_version
$ patch -p1 ../packagename_version-newrevision.debdiff

This should generate no rejections or fuzz

Interdiff patches are best tested with

$ combinediff -z packagename_version-revision.diff.gz packagename_version-newrevision.interdiff > test.diff
$ interdiff -z test.diff packagename_newversion-newrevision.diff.gz
$ rm test.diff

This should generate no output

If you are completely satisfied, request sponsorship for your new revision.

If your new revision required the generation of an interdiff, rebuild the sources with  debuils -S -sa  and upload to [:MOTU/Packages/REVU:REVU]. Note that you must first belong to the [https://launchpad.net/~ubuntu-universe-contributors REVU Upload] Team.

If only one launchpad bug will closed, attach your diff to that bug. If several launchpad bugs will be closed, open a new bug entitled "Candidate revision packagename_version-revision, and include your changelog entry in the bug description. Attach your diff to this new bug. If your revision required an interdiff, be sure to include the REVU entry URL in your comment.

Set the bug to Status "Confirmed". Assign to "Nobody". Subscribe the ubuntu-universe-sponsors team to add your bug to the [:MOTU/Sponsorship/SponsorsQueue:Sponsorship Queue].

Once the revision has been uploaded, check https://launchpad.net/~<your LP ID>/+packages for the status of the autobuilders. Once all builds are complete, set the status of the bug to "Fix Released", and add a comment that it built on all architectures. If the build fails, prepare another revision to fix the build, upload that debdiff to the same bug, reset the Status and Assignment for the bug, and resubscribe ubuntu-universe-sponsors.

While you are waiting, review the bugs that will be closed, to make sure that any that apply to Debian have Debian bugs open, and that any related Debian bugs have patches (you may need to extract individual patches from your diff to send to Debian - see Preparing Patches for hints).

If your new revision closes several launchpad bugs, also remember to adjust the status of all the bugs to be closed.

Preparing New Packages

Prerequisites:

Procedure:

  • Find or report a [https://bugs.launchpad.net/ubuntu/+bugs?field.tag=needs-packaging Needs Packaging] Bug

  • Set the Status to "In Progress" and assign yourself
  • Create a new Package (Some [:MOTU/Packages/Packaging/Tips:Tips] are available)

  • Verify that packagename_version-revision.diff.gz does not change anything outside debian/
  • Make sure you have an Ubuntu version and Ubuntu Maintainer
  • Build the package with [:PbuilderHowto:pbuilder] or [https://help.ubuntu.com/community/SbuildLVMHowto sbuild]

  • Run the lintian and linda tests to make sure there are no obvious problems
  • Review the [:MOTU/Packages/CommonPackagingMistakes:Common Mistakes] to be safe

  • Check the [:MOTU/Packages/Reviewing:Reviewing Guidelines] to catch things before your reviewers have a chance

  • Upload the package to [:MOTU/Packages/REVU:REVU]

  • Add the REVU upload URL to the bug
  • You may, if you wish, announce your upload to #ubuntu-motu not more than once per day
  • Once the package is uploaded, set the bug Status to "Fix Committed"
  • Once the package is approved and distributed in the archives, set the bug Status to "Fix Released"
  • Contact the [http://utnubu.alioth.debian.org/ Utnubu Team] to get your package into Debian

Other Work

Other activities are be listed on the [:MOTU/TODO:MOTU Task List]. Check there if you run out of things to do above, or would just like some variety.

If you've contributed a lot over at least two release cycles, and a couple members of ubuntu-dev have suggested you should, please consider [:MOTU/Hopeful/Recruitment:applying] to join the [:MOTU:MOTU] team.


["CategoryMOTU"]

MOTU/Contributing (last edited 2011-12-10 00:37:40 by allison)