Skip to content

Maintainers' Corner

Jump to bottom Edit New page
Pete Batard edited this page Jul 1, 2013 · 19 revisions

Table of Contents

Pushing changes to libusbx mainline

First, you should not use the oh-so-tempting github "Merge pull request" feature.

The reason is that using github's merge (or a regular git commit/merge if pre-commit/post-rewrite aren't used) will screw up our versioning (libusb/version_nano.h being increased for each commit) which we use to identify both a commit and its chronological order.

The first thing you need to ensure then is that your /.git/hooks/pre-commit and /.git/hooks/post-rewrite reference the relevant scripts from /.private. See the commends in the .sh for details on how to do that.

Regular commits (i.e. a patch you've created from scratch against your repo)

  • Nothing to be done. The versioning update will be done automatically for you, as long as you have the hooks set

Amend of a commit (or: oops, I screwed up my previous commit and need to change it before a push)

In the root of libusbx, you must manually create a .amend file and then run the git commit --amend command. This is the only way I found to make sure git could detect an amend and not increase the nano again. Note however that the scripts are smart enough to tell you if you forgot to create a .amend file on an amend, so providing you pay attention to the messages spewed by git, even if you forget to create one you should still be OK. The scripts will even create the .amend file for you, so if you wanted, you could just run git commit --amend twice to get everything sorted.

Merge of a commit that you didn't create, such as a pull request from github or a patch you got off the mailing list.

  • Well, if it's a pull request from github, the first thing you'll need is a patch file you can merge. The one thing you want to know is that github can easily provide such a thing. Say I want to merge Ludovic's 11071c87245423b71ac1b37fd1452005cef605d7 from github. If I go to https://github.com/LudovicRousseau/libusbx/commit/11071c87245423b71ac1b37fd1452005cef605d7 I get the github web formatted patch, but lo and behold, add .patch at the end, to have https://github.com/LudovicRousseau/libusbx/commit/11071c87245423b71ac1b37fd1452005cef605d7.patch, and you have exactly what you want to use to work with your local tree.
  • Most of the time, once I have the .patch in my repo, I tend to use apply patch serial, for each individual patch. Of course, you can also choose to merge, or use any other method of your choice that will produce the commit you'd like to eventually push to mainline.
  • Now, the operation above will not increase the nano, so after each patch you want to apply, you need to create a .amend, as per B, and amend the previous commit. And yeah, if you apply a bunch of patches at once, having to do an amend on every individual patch can be a bit tedious. On the other hand, most of the time you actually want to amend a patch so that the messages are consistent, or updated, and it gives you greater opportunity to ensure that was you get into mainline has been inspected closely, so I don't see it as that much of a drawback.

RC/Release work

  • Create a github issue for the release task (so that closing the other issues won't flag the milestone as completed before the release)
  • If new APIs were added, ensure the the DLL .def is updated by running the following on a libusb-1.0 DLL generated by MinGW32:
    echo -e "LIBRARY \"libusb-1.0.dll\"\nEXPORTS" > libusb-1.0.def; strings libusb-1.0.dll | grep libusb | grep @ | sort | sed -e "s/\\((.*\\))@\\(([0-9]*\\))/  \1\n  \1@\2 = \1/" >> libusb-1.0.def
  • Update libusb/version.h. If RC, set LIBUSB_RC to "-rc1", etc.
  • Update ChangeLog (and additionally TODO/THANKS)
  • Update AUTHORS and make sure anybody listed with the following is present:
    git shortlog -s | cut -c8-
  • If a new .h was added, make sure it is listed in the relevant Makefile.am, else the tarball will not have it!
  • Run ./autogen.sh
  • Run make distcheck
  • Run make docs-upload in the /doc directory
  • Test the release tarball
  • Create the relevant directories at https://sourceforge.net/projects/libusbx/files/releases and upload the archives
  • Don't forget to push the RC/release commit, so that version.h and tags are updated in the public repo
  • If any bugs were pending actual release, close them
  • If bugs were pending to the milestone, that haven't been completed, move them to the next release
  • On release day, close the release task issue
  • Upload the snapshot(s) (if not automated) and make sure the source tarball is set as the default download
  • Update the project's web page if needed
  • Check that the SourceForge tarball download actually works
  • Update and push the index page from https://github.com/libusbx/libusbx.github.com
  • Send a release notification to libusbx-devel and linux-usb
  • Announce the release on http://freecode.com/ on release day

Updating the project's pages on SF

Add a custom footer
Add a custom sidebar
Clone this wiki locally