GNU Libtool - Contributing

Maintainership

GNU Libtool was conceived, designed and implemented by:

GNU Libtool's Dynamic Loader library (libltdl) was conceived, designed and implemented by:

GNU Libtool and libltdl have previously been maintained, enhanced, ported and otherwise advanced by:

GNU Libtool and libltdl are currently being cajoled, bullied, rewritten and otherwise dragged into the future by:

Applying Patches

When there are multiple maintainers, we co-ordinate changes on the <libtool-patches> list. We observe the following rules when changing the repository:

  • All changes to the trunk of the repository must be posted to <libtool-patches>.
  • After a patch has been posted, it can be committed after it has been approved by one of the maintainers. When there are three or more active maintainers, we ask that they do not "approve" their own patches.
  • A veto from one maintainer puts the patch on hold until the submitter and the objecter can reach a concensus.
  • If a patch is not vetoed within 72 hours of posting, any maintainer can apply it to the repository as if it had been approved.
  • Obvious bug fixes do not need explicit approval, though they must be posted to <libtool-patches> for informational purposes.
  • Changes committed to development branches do not need explicit approval, though they should be posted to <libtool-patches> for informational purposes.

Submitting Bug Reports

Please submit issues and bug reports using Savannah's Tech Support Manager. From the top navigation menu select "Support" > "Submit new" to file a new issue.
In the past the [email protected] list was used to report issues, but tracking and managing issues on this list led to reports falling through the cracks and being missed/forgotten.

If you think you have found a bug in libtool, you should first of all send as complete a report as possible to this list. Ideally, you should include the text you get by running config.guess, the text you see when you run configure, and if you can, a patch made with "diff -u5" which fixes the problem. If you can send a small script, modelled after the scripts in the tests directory of the distribution, which fails with the unpatched distribution, but passes with your patch applied, we can add the test to the distribution to make sure the bug doesn't reappear.

Bug-fix patches may be uploaded from the Tech Support Manager when submitting a new issue, or added later from an issue's tracking page as file attachments. Please follow the guidelines below when writing patches, but keep in mind that you do should not use the Patch Manager for patches associated with a bug report, simply attach it as a file to your issue.

Submitting Patches

Every patch must have several pieces of information before we can properly evaluate it.

  • A description of the bug and how your patch fixes this bug. For new features, a description of the feature and your implementation. Patches which include new test cases are especially welcome.
  • A ChangeLog entry as plaintext; see the various ChangeLog files for format and content.
    Note that, unlike some other projects, we do require ChangeLogs also for documentation (i.e., .texi files).
  • The patch itself. If you are accessing the git repository at gnu.org, use something like "git format-patch --stdout master"; else, use "diff -u OLD NEW". If your version of diff does not support these options, then get the latest version of GNU diff.
  • If your changes add a new feature, please provide documentation as a patch to the texinfo docs.

If you want to be certain that your patch doesn't get lost among the noise on the mailing list, you can also upload a copy to the patch manager at savannah , from the top navigation bar select "Patches" > "Submit new". Please note that the Patch Manager is not intended for bug fixes, which should instead be uploaded as attachments in the relevant bug report.

When you have submitted your patch, somebody will tell you what to do next.

Persistent contributors who submit high quality patches may be given direct git access. You have been warned.

Coding Standards

All contributions must conform to the GNU Coding Standards. Submissions which do not conform to the standards will be returned with a request to reformat the changes.

ChangeLog entries are formatted according to some specific rules:

  • Related changes that form a single logical change to the sources are grouped together into a continuous block – in other words, blank lines occur between logical groups of related changes.
  • There is exactly one commit to the repository for each logical change, as represented by a block of (unseparated) descriptions in the ChangeLog.
  • If it helps, a descriptive block describing the purpose of the change can be added before the first file entry. Consider adding descriptive text to the documentation before you add ChangeLog descriptions.

Copyright Assignment

Before we can accept non-trivial code contributions from you, we need a copyright assignment on file with the FSF. A description of the process is available in the Information for Maintainers. This boils down to the following instructions:

  • If you've developed some addition or patch to Libtool that you would like to contribute, submit it using the Savannah Patch Manager, from the top navigation bar select "Patches" > "Submit new". We might ask you for some more information at this point.
  • You will be sent a short form by email, which you should fill in and email back to the FSF.
  • Once the FSF people have received this email, they will send you a paper copy of the full copyright assignment documents, for you to sign and post back to them.
  • As soon as the signed paperwork is filed at the FSF, we can accept your changes into the source tree.
  • Individual small changes (fewer than 10 lines of code) can, however, be accepted without a copyright assignment form on file.

Release Numbering

Version numbers are chosen to make it easy for users to decide two things:

Q: How “developed” is this release?
A: The higher the number, the better!
Q: How “stable” is this release?
A: If it has a version number ending with a dash and a short hex number, it is a snapshot directly from git, and the hex number is the start of the snapshots SHA1 in git; if it has two numbers only in the version, it is a new stable point release; if it has three numbers in the version, it is a patch release, fixing bugs from the point release but with no new features; if it has four numbers, it is an alpha-quality release moving towards the next patch or stable release.

To make this happen, the maintainers apply patches to the master branch after review, tagging releases as they are made. Before any non-bugfix patch is applied to master, a maintenance branch for the last stable release is made.

Any distribution made from an untagged release in git will have part of that revision's SHA1 appended to the release number, so that the users can tell it is an untested build if they use it.

git conventions

The source for libtool is managed collaboratively in git on the FSF Savannah system. The conventions set out below represent how we plan to do things from here on in, although historically, the tree has not been maintained in quite the same way.

  • The git master branch, which you get if you don't specify a tag when you checkout, represents the latest development of the code. This means that master guarantees you the latest, greatest code and the most stability problems!
  • Each stable release is tagged, and maintenance releases are made from a separate maintenance branch unless master has not received any destabilising changes, so that bug fixes can be applied independently to release versions.
  • Feel free to create your own private development branches. We also encourage you to create shared branches, but please announce them before pushing them to savannah. For public branches, it is necessary to state a policy whether they will only move forward, or be rewound/rebased against master from time to time.

git tag names

Libtool releases three types of source tarballs from git:

  1. Alpha releases are the lowest quality tarballs we build. They come from master, and indicate that a new point release is coming. You can distinguish an alpha by its four-part version number: 2.5.0.1 and 2.5.0.4 for example. Alpha releases are tagged in git as v[major].[minor].0.[alpha-count]: v2.5.0.1 and v2.5.0.4 here.
  2. Point releases are normally reasonably stable. A point release is the first release made from a new release branch. You can distinguish it because it has only major and minor parts in its version number: 2.2 and 2.4 for example. Point releases are tagged in git as v[major].[minor]: v2.2 and v2.4 here.
  3. Patch releases are only ever made from the most recent release branch and never contain any new features over the point release they fix. You can distinguish a patch release, because it carries a numeric micro version suffix: 2.2.6 and 2.4.2 for example. Patch releases are tagged in git as v[major].[minor].[micro].