Contributing

Why Contribute to MOTU

  • 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

Recommended Preparation:

There are a lot of bugs in Universe: many of them have fairly simple fixes, and others have known or easily developed solutions. 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 Patching Guide to determine how to create a patch. If there is no patch system, 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 Debian 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

Recommended Preparation:

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 Debian BTS  http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=packagename 

  3. The upstream bugtracker (the upstream homepage should be in debian/copyright)
  4. If the package has an Ubuntu version, check with the last uploader for possible pending changes
  5. After a test build, the output of any of the package analysis commands: 

$ 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/

If you have the A URL for the description (.dsc) file, you can also download the sources with: 

$ dget -x dsc-file-URL

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 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 sbuild or 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 the Maintainer set as per the DebianMaintainerField specification.

  • 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, not derived from Debian, the newly generated diff.gz file is the best format of the patch.

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

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

If only one launchpad bug will closed, attach your diff to that bug. If several launchpad bugs will be closed, you may, if requested by a sponsor or if you believe it would reduce confusion, 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. Don't forget to close this new bug in the changelog. e.g. 

  * Bug fix upload (LP: #345678)
   - Fixed foo (LP: #123456)
   - Fixed bar (LP: #234567)

Set the bug to Status "Confirmed". Assign to "Nobody". Subscribe the ubuntu-sponsors team to add your bug to the Sponsorship Queue.

Once the revision has been uploaded it will automatically be marked fix released, check https://launchpad.net/people/+me/+packages for the status of the autobuilders. 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-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

Recommended Preparation:

Procedure:

  • Find or report a Needs Packaging Bug

  • Set the Status to "In Progress" and assign yourself

  • Create a new Package (Check Out PackagingGuide#Basic)

  • Verify that packagename_version-revision.diff.gz does not change anything outside debian/

  • Make sure you have an Ubuntu version and a Maintainer set as per the DebianMaintainerField specification.

  • Build the package with pbuilder or sbuild

  • Run the lintian tests to make sure there are no obvious problems
  • Make sure the debian/watch file works to track new versions

  • Review the Common Mistakes to be safe

  • Check the Reviewing Guidelines to catch things before your reviewers have a chance

  • Upload the package to your PPA
  • Add the PPA 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 approved and uploaded to the archive, set the bug Status to "Fix Committed"
  • Once the package is accepted by the archive administrators and distributed in the archives, set the bug Status to "Fix Released"

  • Check out ContributingToDebian to find out how to get your package included in Debian.

Other Activities

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

Joining MOTU

Once your sponsors encourage you to become a MOTU yourself, please consider applying to join the MOTU team.

CategoryMOTU

MOTU/Contributing (last edited 2011-12-10 00:37:40 by static-50-53-26-176)