6.1 Copyright Papers

If you maintain an FSF-copyrighted package, certain legal procedures are required when incorporating legally significant changes written by other people. This ensures that the FSF has the legal right to distribute the package, and the standing to defend its GPL-covered status in court if necessary.

GNU packages need not be FSF-copyrighted; this is up to the author(s), generally at the time the package is dubbed GNU. When copyright is assigned to the FSF, the FSF can act to stop GPL violations about the package. Otherwise, legal actions are up to the author(s). The rest of this section is about the case when a package is FSF-copyrighted.

Before incorporating significant changes, make sure that the person who wrote the changes has signed copyright papers and that the Free Software Foundation has received and signed them. We may also need an employer’s disclaimer from the person’s employer, which confirms that the work was not part of the person’s job and the employer makes no claim on it. However, a copy of the person’s employment contract, showing that the employer can’t claim any rights to this work, is often sufficient.

If the employer does claim the work was part of the person’s job, and there is no clear basis to say that claim is invalid, then we have to consider it valid. Then the person cannot assign copyright, but the employer can. Many companies have done this. Please ask the appropriate managers to contact assign@gnu.org.

To check whether papers have been received, look in /gd/gnuorg/copyright.list. If you can’t look there directly, fsf-records@gnu.org can check for you. Our clerk can also check for papers that are waiting to be entered and inform you when expected papers arrive.

The directory /gd/gnuorg mentioned throughout this document is available on the general GNU server, currently fencepost.gnu.org. If you are the maintainer of a GNU package, you should have an account there. If you don’t have one already, see https://www.gnu.org/software/README.accounts.html. Such GNU login accounts include email (see https://www.fsf.org/about/systems/sending-mail-via-fencepost).

You can request for accounts for people who significantly help you in working on the package; we will do this in special cases when there is a good reason.

In order for the contributor to know person should sign papers, you need to ask per for the necessary papers. If you don’t know per well, and you don’t know that person is used to our ways of handling copyright papers, then it might be a good idea to raise the subject with a message like this:

Would you be willing to assign the copyright to the Free Software Foundation, so that we could install it in package?

or

Would you be willing to sign a copyright disclaimer to put this change in the public domain, so that we can install it in package?

If the contributor then wants more information, you can send per the file /gd/gnuorg/conditions.text, which explains per options (assign vs. disclaim) and their consequences.

Once the conversation is under way and the contributor is ready for more details, you should send one of the templates that are found in the directory /gd/gnuorg/Copyright/; they are also available from the doc/Copyright/ directory of the gnulib project at https://savannah.gnu.org/projects/gnulib. This section explains which templates you should use in which circumstances. Please don’t use any of the templates except for those listed here, and please don’t change the wording.

Once the conversation is under way, you can send the contributor the precise wording and instructions by email. Before you do this, make sure to get the current version of the template you will use! We change these templates occasionally—don’t keep using an old version.

For large changes, ask the contributor for an assignment. Send per a copy of the file request-assign.changes. (Like all the ‘request-’ files, it is in /gd/gnuorg/Copyright and in gnulib.)

For medium to small changes, request a personal disclaimer by sending per the file request-disclaim.changes.

If the contributor is likely to keep making changes, person might want to sign an assignment for all per future changes to the program. So it is useful to offer per that alternative. If person wants to do it that way, send per the request-assign.future.

When you send a request- file, you don’t need to fill in anything before sending it. Just send the file verbatim to the contributor. The file gives per instructions for how to ask the FSF to mail per the papers to sign. The request- file also raises the issue of getting an employer’s disclaimer from the contributor’s employer.

When the contributor emails the form to the FSF, the FSF sends per an electronic (usually PDF) copy of the assignment. This, or whatever response is required, should happen within five business days of the initial request. If no reply from the FSF comes after that time, please send a reminder. If there is still no response after an additional week, please write to maintainers@gnu.org about it.

After receiving the necessary form, the contributor needs to sign it. Contributors residing in the USA or Italy may use GPG in order to sign their assignment. Contributors located anywhere else can print, sign, and then email (or fax) a scanned copy back to the FSF. (Specific instructions for both cases are sent with the assignment form.) They may use postal mail, if they prefer. To emphasize, the necessary distinction is between residents and non-residents of these countries; citizenship does not matter.

For less common cases, we have template files you should send to the contributor. Be sure to fill in the name of the person and the name of the program in these templates, where it says ‘NAME OF PERSON’ and ‘NAME OF PROGRAM’, before sending; otherwise person might sign without noticing them, and the papers would be useless. Note that in some templates there is more than one place to put the name of the program or the name of the person; be sure to change all of them. All the templates raise the issue of an employer’s disclaimer as well.

You do not need to ask for separate papers for a manual that is distributed only in the software package it describes. But if we sometimes distribute the manual separately (for instance, if we publish it as a book), then we need separate legal papers for changes in the manual. For smaller changes, use disclaim.changes.manual; for larger ones, use assign.changes.manual. To cover both past and future changes to a manual, you can use assign.future.manual. For a translation of a manual, use assign.translation.manual.

For translations of program strings (as used by GNU Gettext, for example; see Internationalization in GNU Coding Standards), use disclaim.translation. If you make use of the Translation Project (https://translationproject.org) facilities, please check with the TP coordinators that they have sent the contributor the papers; if they haven’t, then you should send the papers. In any case, you should wait for the confirmation from the FSF that the signed papers have been received and accepted before integrating the new contributor’s material, as usual.

If a contributor is reluctant to sign an assignment for a large change, and is willing to sign a disclaimer instead, that is acceptable, so you should offer this alternative if it helps you reach agreement. We prefer an assignment for a larger change, so that we can enforce the GNU GPL for the new text, but a disclaimer is enough to let us use the text.

If you maintain a collection of programs, occasionally someone will contribute an entire separate program or manual that should be added to the collection. Then you can use the files request-assign.program, disclaim.program, assign.manual, and disclaim.manual. We very much prefer an assignment for a new separate program or manual, unless it is quite small, but a disclaimer is acceptable if the contributor insists on handling the matter that way.

When a copyright holder has signed an assignment for all future changes to the package, and contributes a change made up of new files which require no change to any of the old files, we want to avoid any uncertainty about whether these files are intended as a change to the package and thus covered by that assignment. The way to do this is to ask the contributor to say so in a message to you — for instance, “My modules ‘frog’ and ‘kangaroo’ are intended as changes to the program Hoppers.” Forward the message to assign@gnu.org, who will save it permanently. A variation on this procedure: the contributor who wrote the new files can send copies of the new files which contain such a message.

If a contributor wants the FSF to publish only a pseudonym, that is ok. The contributor should say this, and state the desired pseudonym, when answering the request- form. The actual legal papers will use the real name, but the FSF will publish only the pseudonym. When using one of the other forms, fill in the real name but ask the contributor to discuss the use of a pseudonym with assign@gnu.org before sending back the signed form.

Although there are other templates besides the ones listed here, they are for special circumstances; please do not use them without getting advice from assign@gnu.org.

If you are not sure what to do, then please ask assign@gnu.org for advice; if the contributor asks you questions about the meaning and consequences of the legal papers, and you don’t know the answers, you can forward them to assign@gnu.org and we will answer.

Please do not try changing the wording of a template yourself. If you think a change is needed, please talk with assign@gnu.org, and we will work with a lawyer to decide what to do.

6.2 Legally Significant Changes

If a person contributes more than around 15 lines of code and/or text that is legally significant for copyright purposes, we need copyright papers for that contribution, as described above.

A change of just a few lines (less than 15 or so) is not legally significant for copyright. A regular series of repeated changes, such as renaming a symbol, is not legally significant even if the symbol has to be renamed in many places. Keep in mind, however, that a series of minor changes by the same person can add up to a significant contribution. What counts is the total contribution of the person; it is irrelevant which parts of it were contributed when.

Copyright does not cover ideas. If someone contributes ideas but no text, these ideas may be morally significant as contributions, and worth giving credit for, but they are not significant for copyright purposes. Likewise, bug reports do not count for copyright purposes.

When giving credit to people whose contributions are not legally significant for copyright purposes, be careful to make that fact clear. The credit should clearly say they did not contribute significant code or text.

When people’s contributions are not legally significant because they did not write code, do this by stating clearly what their contribution was. For instance, you could write this:

/*
 * Ideas by:
 *   Richard Mlynarik <mly@adoc.xerox.com> (1997)
 *   Masatake Yamato <masata-y@is.aist-nara.ac.jp> (1999)
 */

Ideas by: makes it clear that Mlynarik and Yamato here contributed only ideas, not code. Without the Ideas by: note, several years from now we would find it hard to be sure whether they had contributed code, and we might have to track them down and ask them.

When you record a small patch in a change log file, first search for previous changes by the same person, and see if per past contributions, plus the new one, add up to something legally significant. If so, you should get copyright papers for all per changes before you install the new change.

If that is not so, you can install the small patch. Write ‘(tiny change)’ after the patch author’s name, like this:

2002-11-04  Robert Fenk  <Robert.Fenk@gmx.de>  (tiny change)

6.3 Recording Contributors

Keep correct records of which portions were written by whom. This is very important. These records should say which files or parts of files were written by each person, and which files or parts of files were revised by each person. This should include installation scripts as well as manuals and documentation files—everything.

These records don’t need to be as detailed as a change log. They don’t need to distinguish work done at different times, only different people. They don’t need describe changes in more detail than which files or parts of a file were changed. And they don’t need to say anything about the function or purpose of a file or change—the Register of Copyrights doesn’t care what the text does, just who wrote or contributed to which parts.

The list should also mention if certain files distributed in the same package are really a separate program.

Only the contributions that are legally significant for copyright purposes (see Legally Significant Changes) need to be listed. Small contributions, bug reports, ideas, etc., can be omitted.

For example, this would describe an early version of GAS:

Dean Elsner   first version of all files except gdb-lines.c and m68k.c.
Jay Fenlason  entire files gdb-lines.c and m68k.c, most of app.c,
              plus extensive changes in messages.c, input-file.c, write.c
              and revisions elsewhere.

Note: GAS is distributed with the files obstack.c and obstack.h, but
they are considered a separate package, not part of GAS proper.

Please keep these records in a file named AUTHORS in the source directory for the program itself.

You can use the change log as the basis for these records, if you wish. Just make sure to record the correct author for each change (the person who wrote the change, not the person who installed it), and add ‘(tiny change)’ for those changes that are too trivial to matter for copyright purposes. Later on you can update the AUTHORS file from the change log. This can even be done automatically, if you are careful about the formatting of the change log entries.

It is ok to include other email addresses, names, and program information in AUTHORS, such as bug-reporting information. See Standard Mailing Lists.

6.4 Copying from Other Packages

This section explains legal considerations when merging code from other packages into your package. Using an entire module as a whole, and maintaining its separate identity, is a different issue; see External Libraries.

• Non-FSF-Copyrighted Package
• FSF-Copyrighted Package

6.5 Copyright Notices

You should maintain a proper copyright notice and a license notice in each nontrivial file in the package. (Any file more than ten lines long is nontrivial for this purpose.) This includes header files and interface definitions for building or running the program, documentation files, and any supporting files. If a file has been explicitly placed in the public domain, then instead of a copyright notice, it should have a notice saying explicitly that it is in the public domain.

Even image files and sound files should contain copyright notices and license notices, if their format permits. Some formats do not have room for textual annotations; for these files, state the copyright and copying permissions in a README file in the same directory.

Change log files should have a copyright notice and license notice at the end, since new material is added at the beginning but the end remains the end.

When a file is automatically generated from some other file in the distribution, it is useful for the automatic procedure to copy the copyright notice and permission notice of the file it is generated from, if possible. Alternatively, put a notice at the beginning saying which file it is generated from.

A copyright notice looks like this:

Copyright (C) year1, year2, year3 copyright-holder

The word ‘Copyright’ must always be in English, by international convention.

The copyright-holder may be the Free Software Foundation, Inc., or someone else; you should know who is the copyright holder for your package.

Replace the ‘(C)’ with a C-in-a-circle symbol if it is available. For example, use ‘@copyright{}’ in a Texinfo file. However, stick with parenthesized ‘C’ unless you know that C-in-a-circle will work. For example, a program’s standard --version message should use parenthesized ‘C’ by default, though message translations may use C-in-a-circle in locales where that symbol is known to work. Alternatively, the ‘(C)’ or C-in-a-circle can be omitted entirely; the word ‘Copyright’ suffices.

To update the list of year numbers, add each year in which you have made nontrivial changes to the package. (Here we assume you’re using a publicly accessible revision control server, so that every revision installed is also immediately and automatically published.) When you add the new year, it is not required to keep track of which files have seen significant changes in the new year and which have not. It is recommended and simpler to add the new year to all files in the package, and be done with it for the rest of the year.

Don’t delete old year numbers, though; they are significant since they indicate when older versions might theoretically go into the public domain, if the movie companies don’t continue buying laws to further extend copyright. If you copy a file into the package from some other program, keep the copyright years that come with the file.

You can use a range (‘2008-2010’) instead of listing individual years (‘2008, 2009, 2010’) if and only if: 1) every year in the range, inclusive, really is a “copyrightable” year that would be listed individually; and 2) you make an explicit statement in a README file about this usage.

For files which are regularly copied from another project (such as ‘gnulib’), leave the copyright notice as it is in the original.

The copyright statement may be split across multiple lines, both in source files and in any generated output. This often happens for files with a long history, having many different years of publication.

For an FSF-copyrighted package, if you have followed the procedures to obtain legal papers, each file should have just one copyright holder: the Free Software Foundation, Inc. You should edit the file’s copyright notice to list that name and only that name.

But if contributors are not all assigning their copyrights to a single copyright holder, it can easily happen that one file has several copyright holders. Each contributor of nontrivial text is a copyright holder.

In that case, you should always include a copyright notice in the name of main copyright holder of the file. You can also include copyright notices for other copyright holders as well, and this is a good idea for those who have contributed a large amount and for those who specifically ask for notices in their names. (Sometimes the license on code that you copy in may require preserving certain copyright notices.) But you don’t have to include a notice for everyone who contributed to the file (which would be rather inconvenient).

Sometimes a program has an overall copyright notice that refers to the whole program. It might be in the README file, or it might be displayed when the program starts up. This copyright notice should mention the year of completion of the most recent major version; it can mention years of completion of previous major versions, but that is optional.

6.6 License Notices

Every nontrivial file needs a license notice as well as the copyright notice. (Without a license notice giving permission to copy and change the file, the file is nonfree.)

The package itself should contain a full copy of GPL in plain text (conventionally in a file named COPYING) and the GNU Free Documentation License (included within your documentation, so there is no need for a separate plain text version). If the package contains any files distributed under the Lesser GPL, it should contain a full copy of its plain text version also (conventionally in a file named COPYING.LESSER).

If you have questions about licensing issues for your GNU package, please write licensing@gnu.org.

• Licensing of GNU Packages
• Canonical License Sources
• License Notices for Code
• License Notices for Documentation
• License Notices for Code Examples
• License Notices for Other Files

This file is part of GNU package.

GNU package is free software: you can redistribute it and/or
modify it under the terms of either:

  * the GNU Lesser General Public License as published by the Free
    Software Foundation; either version 3 of the License, or (at your
    option) any later version.

or

  * the GNU General Public License as published by the Free
    Software Foundation; either version 2 of the License, or (at your
    option) any later version.

or both in parallel, as here.

GNU package is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received copies of the GNU General Public License and
the GNU Lesser General Public License along with this program.  If
not, see https://www.gnu.org/licenses/.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License'', with the
Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts
as in (a) below.  A copy of the license is included in the section
entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have the freedom to
copy and modify this GNU manual.  Buying copies from the FSF
supports it in developing GNU and promoting software freedom.''

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.  This file is offered as-is,
without any warranty.

6.7 External Libraries

As maintainer of an FSF-copyrighted GNU package, how do you use separately-published general-purpose free modules? (We also call them “libraries” because we are using them as libraries; it doesn’t matter whether they are packaged as libraries or not.)

It would be unreasonable to ask their authors to assign copyright to the FSF. They didn’t write those modules as contributions to GNU. We just happen to want to use them, as any developer might. It would be rude to ask developers, out of the blue, to give the FSF their copyright. Please don’t ask for that in cases like these.

The proper way to use those modules is to link your package with them and say they are not part of your package. See below for the mechanics of this.

To avoid present or future legal trouble, you must make sure the license of the module is compatible with current and future GPL versions. “GNU GPL version 3 or later” is good, and so is anything which includes permission for use under those GPL versions (including “GNU GPL version 2 or later”, “LGPL version n or later”, “LGPL version 2.1”, “GNU Affero GPL version 3 or later”). Lax permissive licenses are ok too, since they are compatible with all GPL versions.

“GPL version 2 only” is obviously unacceptable because it is incompatible with GPL version 3. “GPL version 3 only” and “GPL version 2 or 3 only” have a subtler problem: they would be incompatible with GPL version 4, if we ever make one, so the module would become an obstacle to upgrading your package’s license to “GPL version 4 or later”. Don’t use such modules.

One library you need to avoid is goffice, since it allows only GPL versions 2 and 3.

So, here are the mechanics of how to arrange your package to use the unrelated free module.

1. Assume the module is already installed on the system, and link with it when linking your program. This is only reasonable if the module really has the form of a library.
2. Include the module in your package’s distribution, putting the source in a separate subdirectory whose README file says, “This is not part of the GNU FOO program, but is used with GNU FOO.” Then set up your makefiles to build this module and link it into the executable.

   With this method, it is not necessary to treat the module as a library and make a ‘.a’ file from it. You can link directly with the ‘.o’ files in the usual manner.

Both of these methods create an irregularity, and our lawyers have told us to minimize the amount of such irregularity. So use these methods only for general-purpose modules that were not written for your package. For anything that was written as a contribution to your package, please get papers signed.

6.8 Crediting Authors

Strictly speaking, this is not a legal issue, but it seems to belong with copyright notices.

In any FSF-copyrighted GNU package, the authors of a file are not named in the copyright notice. Therefore, it is nice to include a comment line ‘Authors: authors of this file’ at the top near the copyright notice, to give them credit in close association with their contribution.

9.1 Don’t Install a Feature Till It Works on GNU

Please don’t write or install code for features that would have worse or less functionality (or none) on the GNU system than on some non-GNU systems.

The primary purpose of any GNU program is to enhance the capability of the GNU system to give users freedom, so every feature of a GNU package should be usable and useful on free distributions of the GNU operating system (https://www.gnu.org/distros/). For this purpose, a “feature” is an operation which does something substantially useful for the user and not the technical details of an implementation. We explain this point further below.

A feature that functions only on, or functions better on, some non-GNU operating system would undermine that primary purpose; worse, it would promote that non-GNU system at the expense of GNU. Such a situation would work directly against the goal of liberating users from those systems, even though installing features that create such a situation would be seen as desirable in terms of the “open source” philosophy.

Since freedom in use of computing is the overall purpose, we need to aim clearly for that freedom. We need to show with our practical decisions—and with our explanations of them—that we’re working for something deeper and more important than “better software” and “more convenience.” That will give users a chance to reflect about our reasons for taking a path different from what most programmers would do. See https://www.gnu.org/philosophy/open-source-misses-the-point.html.

Therefore, when you as a GNU maintainer receive contributions of features that do not work on the GNU system, please explain this rule and why it is necessary. Explain that we need all features in GNU packages to work properly on the GNU system, so that they potentiate each other and make the GNU system better. Thus, the change should not be installed in its present form.

That doesn’t mean the change can’t be installed ever. It could be installed later, if and when equally good support on the GNU system for the same feature can be installed at the same time. Explaining this is a good opportunity to ask people to help write the code to support the feature on GNU. Also inform the contributor about resources to learn about how to support this feature on GNU, so perse could consider doing that job—or recruiting others to help.

If parts of the code are system-independent, and will do part of the job of supporting the feature on the GNU system, you can install them right away. Or you can put them in the package repo without actually installing them, in a ‘wip-name’ branch. Having them in the repository may help and encourage people to finish implementing the feature on GNU.

If you think it is very important, you can implement the support for that feature on the GNU system yourself. If you think it is highly desirable to have that feature on GNU someday, you can make special arrangements to put the non-GNU system-specific code in the package repo but not install it—see Uninstalled Code in Repo.

It is ok to implement or support a feature for non-GNU systems if the feature works at least as well on GNU, even if it is implemented differently on different systems, uses different system facilities in its implementation, or looks different to the user in some details. It is ok to implement those little details, on each system, in the way that is convenient or conventional for making the features work. The point is that the program and the feature should “run best on GNU.”

If system facilities on some other system provide, without any special application code, a feature not available on GNU, there is no need to do work to prevent it from functioning. In that case, we should work to implement that feature in GNU.

We don’t consider the little details of interfaces to control or configure specific operations, or details of implementing operations, as “features.” Likewise, a system facility (including libraries that come with the system) is a means for implementing features but use of the facility is not in itself a feature.

For instance, a programming platform often offers an interface to control the computer or the operating system at a low level. It is OK to support the feature of low-level control on a non-GNU system provided the package supports the same capabilities on the GNU system also, even if the details of how to invoke the feature vary from system to system. But do undertake to make the invocation of this feature consistent across systems, for the specific actions that are supported on multiple systems.

Features mainly for communicating with other users’ computers, or between computers not set up for tightly-coupled use as a group, are a different matter entirely. A communication feature is truly “the same feature” as on GNU only if it interoperates with a free distribution of the GNU system—as, for instance, TCP/IP does. Unportable, system-specific communication facilities for non-GNU systems are abuse of the community, so don’t install support for them. This point also applies to file formats used for communication between programs, if there is ever an occasion to move those files between unrelated computers. (Exception: it is admirable to write code to extract the user’s data from such a file, if you can do it.)

Finally, please be careful not to let installing or supporting system-specific code for non-GNU systems consume much of your own time. See GNU Coding Standards in GNU Coding Standards.

Suppose people ask for support for feature F on some non-GNU system, and feature F does work on GNU. You can say yes if you wish, but you have no obligation to write or maintain that code. You can tell them that it’s their responsibility to write it and maintain it. If they write good clean code for it, you can approve its installation, but that doesn’t mean you or anyone else is obliged to support it. If someday the code suffers from bitrot, you can delete it if users don’t fix it.

See Suggested Responses, for some text you can use or adapt, if you like, to say no to these patches. It aims to invite them to support the GNU system equally well in the new feature. If there is no hope of that, just “No thanks” is enough.

9.2 Interoperation with Nonfree Applications

It is quite usual to implement features in GNU programs to make them work conveniently with widely used nonfree tools and applications. But there are situations where you should not implement cooperation with a nonfree program, which we can refer to here as ShackleMe.

• If ShackleMe is not well-known, reject the idea. GNU packages should not even mention an obscure nonfree program (see References in GNU Coding Standards).
• If ShackleMe imposes something particularly nasty or dangerous, such as effective DRM or monopolistic file formats, you should refuse to give it any specific support. But don’t cripple general features so that they refuse to work with ShackleMe; that would be excessive. It is ok to write code to extract the user’s data from such files, if that is possible.
• If ShackleMe does not run on the GNU operating system, and there is no comparable free program that people could use on the GNU system to do the same job, special support for ShackleMe would be a feature that works on non-GNU systems only. Thus, you should refuse to support it. See Don’t Install a Feature Till It Works on GNU.
• If ShackleMe runs on GNU systems also, you can include support for it if you wish, but you don’t have an obligation to include that, let alone ever to run it. If you do include support for it, make sure the support for communicating with it works as well on the GNU system as it does on non-GNU systems.
• If there are free programs that can replace ShackleMe, or try to, make sure your program works with them as well as it is reported to work with ShackleMe, or better.
• You never have an obligation to write, install or maintain any sort of support for a nonfree program. If it is unmaintained and breaks, and nobody else wants to maintain it you can delete it. Don’t feel trapped into working on it!

See Suggested Responses, for text you can use, if you wish, to state your refusal to support ShackleMe without equally good support for ShackleMe’s free competitors. Its purpose is to invite the contributors to support those. You can modify it as needed to fit the situation.

9.3 Uninstalled Code in Repo

When you want to put system-dependent code for a non-GNU feature into the package repository, without actually installing it, you need to make special arrangements with the GNU Project.

To do that, you write to maintainers@gnu.org and explain the feature, its dependance on some other system, and the obstacle that has prevented supporting it on GNU. They will make sure you understand the situation and the arrangements, and get your commitment to make the branch fade away later, in the proper way, if the feature goes unfinished.

Practically speaking, these special arrangements mean you put the code in the package repository in a discouraged branch to show it is not installed, that you have no commitment to finish it, and that it might fade away. Name the branch ‘ungnu-temp/name’. (If that name doesn’t fit with the version control system you use, we will work out a solution.)

Put in the branch a README file saying this:

This code partially implements the what is it feature.  We can't
install it now because it needs to be finished, so that it runs on the
GNU system.

We invite you to write the missing code to implement this feature on
GNU, so we can install the feature.  Until then, this branch must not
be merged into any branch that might ever be released.

See the section "Don't Install a Feature Until It Works on GNU", in the
GNU Maintainer's Guide, for explanation of the reasons for this.

The discouraged branch “fades away” because you don’t merge in changes from the program’s trunk of development. If the branch gets too obsolete to work at all, you simply delete it.

10.1 Standard Mailing Lists

Once a program is in use, you will get bug reports for it. Most GNU programs have their own special lists for sending bug reports. The advertised bug-reporting email address should always be ‘bug-package@gnu.org’, to help show users that the program is a GNU package, but it is ok to set up that list to forward to another site if you prefer.

We also have a catch-all list, bug-gnu-utils@gnu.org, which is used for all GNU programs that don’t have their own specific lists. But nowadays we want to give each program its own bug-reporting list and move away from using bug-gnu-utils.

See Replying to Mail, for more about handling and tracking bug reports.

Some GNU programs with many users have a help list, ‘help-package@gnu.org’, for people to ask other users for help. If your program has many users, you should create such a list for it. For a fairly new program, which doesn’t have a large user base yet, it is better not to bother with this.

If you wish, you can also have a mailing list ‘info-package@gnu.org’ for announcements (see Announcing Releases). Any other mailing lists you find useful can also be created.

The package distribution should state the name of all the package’s mailing lists in a prominent place, and ask users to help us by reporting bugs appropriately. The top-level README file and/or AUTHORS file are good places. Mailing list information should also be included in the manual and the package web pages (see Web Pages).

10.2 Creating Mailing Lists

Using the web interface on savannah.gnu.org is by far the easiest way to create normal mailing lists, managed through Mailman on the GNU mail server. Once you register your package on Savannah, you can create (and remove) lists yourself through the ‘Mailing Lists’ menu, without needing to wait for intervention by anyone else. Furthermore, lists created through Savannah will have a reasonable default configuration for antispam purposes (see below).

To create and maintain simple aliases and unmanaged lists, you can edit /com/mailer/aliases on the main GNU server. If you don’t have an account there, please read https://www.gnu.org/software/README.accounts.html (see GNU Accounts and Resources).

But if you don’t want to learn how to do those things, you can ask new-mailing-list@gnu.org to help you.

You should moderate postings from non-subscribed addresses on your mailing lists, to prevent propagation of unwanted messages (“spam”) to subscribers and to the list archives. For lists controlled by Mailman, you can do this by setting Privacy Options - Sender Filter - generic_nonmember_action to Hold, and then periodically (daily is best) reviewing the held messages, accepting the real ones and discarding the junk.

Lists created through Savannah will have this setting, and a number of others, such that spam will be automatically deleted (after a short delay). The Savannah mailing list page describes all the details. You should still review the held messages in order to approve any that are real.

10.3 Replying to Mail

When you receive bug reports, keep in mind that bug reports are crucial for your work. If you don’t know about problems, you cannot fix them. So always thank each person who sends a bug report.

You don’t have an obligation to give more response than that, though. The main purpose of bug reports is to help you contribute to the community by improving the next version of the program. Many of the people who report bugs don’t realize this—they think that the point is for you to help them individually. Some will ask you to focus on that instead of on making the program better. If you comply with their wishes, you will have been distracted from the job of maintaining the program.

For example, people sometimes report a bug in a vague (and therefore useless) way, and when you ask for more information, they say, “I just wanted to see if you already knew the solution” (in which case the bug report would do nothing to help improve the program). When this happens, you should explain to them the real purpose of bug reports. (A canned explanation will make this more efficient.)

When people ask you to put your time into helping them use the program, it may seem “helpful” to do what they ask. But it is much less helpful than improving the program, which is the maintainer’s real job.

By all means help individual users when you feel like it, if you feel you have the time available. But be careful to limit the amount of time you spend doing this—don’t let it eat away the time you need to maintain the program! Know how to say no; when you are pressed for time, just “thanks for the bug report—I will fix it” is enough response.

Some GNU packages, such as Emacs and GCC, come with advice about how to make bug reports useful. Copying and adapting that could be very useful for your package.

If you would like to use an email-based bug tracking system, see https://bugs.gnu.org; this can be connected with the regular bug-reporting address. Alternatively, if you would like to use a web-based bug tracking system, Savannah supports this (see Recording Old Versions), but please don’t fail to accept bugs by regular email as well—we don’t want to put up unnecessary barriers against users submitting reports.

12.1 Distribution tar Files

All packages should provide tar files for the distribution of their releases. The tar file for version m.n of program foo should be named foo-m.n.tar. It should unpack into a subdirectory named foo-m.n. Tar files should not unpack into files in the current directory, because this is inconvenient if the user happens to unpack into a directory with other files in it.

Here is how the Makefile for Bison creates the tar file. This method is good for other programs.

dist: bison.info
        echo bison-`sed -e '/version_string/!d' \
          -e 's/[^0-9.]*\([0-9.]*\).*/\1/' -e q version.c` > .fname
        -rm -rf `cat .fname`
        mkdir `cat .fname`
        dst=`cat .fname`; for f in $(DISTFILES); do \
           ln $(srcdir)/$$f $$dst/$$f || { echo copying $$f; \
             cp -p $(srcdir)/$$f $$dst/$$f ; } \
        done
        tar --gzip -chf `cat .fname`.tar.gz `cat .fname`
        -rm -rf `cat .fname` .fname

Source files that are symbolic links to other file systems cannot be installed in the temporary directory using ln, so use cp if ln fails.

Using Automake is a good way to take care of writing the dist target.

12.2 Distribution Patches

If the program is large, it is useful to make a set of diffs for each release, against the previous important release.

At the front of the set of diffs, put a short explanation of which version this is for and which previous version it is relative to. Also explain what else people need to do to update the sources properly (for example, delete or rename certain files before installing the diffs).

The purpose of having diffs is that they are small. To keep them small, exclude files that the user can easily update. For example, exclude info files, DVI files, tags tables, output files of Bison or Flex. In Emacs diffs, we exclude compiled Lisp files, leaving it up to the installer to recompile the patched sources.

When you make the diffs, each version should be in a directory suitably named—for example, gcc-2.3.2 and gcc-2.3.3. This way, it will be very clear from the diffs themselves which version is which.

If you use GNU diff to make the patch, use the options ‘-rc2P’. That will put any new files into the output as “entirely different”. Also, the patch’s context diff headers should have dates and times in Universal Time using traditional Unix format, so that patch recipients can use GNU patch’s ‘-Z’ option. For example, you could use the following Bourne shell command to create the patch:

LC_ALL=C TZ=UTC0 diff -rc2P gcc-2.3.2 gcc-2.3.3 | \
gzip -9 >gcc-2.3.2-2.3.3.patch.gz

If the distribution has subdirectories in it, then the diffs probably include some files in the subdirectories. To help users install such patches reliably, give them precise directions for how to run patch. For example, say this:

To apply these patches, cd to the main directory of the program
and then use ‘patch -p1’.   ‘-p1’ avoids guesswork in choosing
which subdirectory to find each file in.

It’s wise to test your patch by applying it to a copy of the old version, and checking that the result exactly matches the new version.

12.3 Binary Distribution for Nonfree Platforms

Some package maintainers release pre-compiled binaries for proprietary systems such as Microsoft Windows or MacOS. It’s entirely up to you whether to do that; we don’t ask you to do it, but we don’t object. Please do not let anyone make you feel you have an obligation to do this.

If you distribute them, please inform their users prominently that those nonfree platforms trample their freedom. It is useful to refer them to https://www.gnu.org/philosophy/free-software-even-more-important.html. You can say, “This program respects your freedom, but Windows does not. To have freedom, you need to stop using Windows and other software that denies your freedom.”

12.4 Distribution on ftp.gnu.org

We strongly recommend using ftp.gnu.org to distribute official releases. If you want to also distribute the package from a site of your own, that is fine. To use some other site instead of ftp.gnu.org is acceptable, provided it allows connections from anyone anywhere.

See Automated FTP Uploads, for the procedural details of putting new versions on ftp.gnu.org.

12.5 Test Releases

When you release a greatly changed new major version of a program, you might want to do so as a pretest. This means that you make a tar file, but send it only to a group of volunteers that you have recruited. (Use a suitable GNU mailing list/newsgroup to recruit them.)

We normally use the server alpha.gnu.org for pretests and prerelease versions. See Automated FTP Uploads, for the procedural details of putting new versions on alpha.gnu.org.

Once a program gets to be widely used and people expect it to work solidly, it is a good idea to do pretest releases before each “real” release.

There are three ways of handling version numbers for pretest versions. One method is to treat them as versions preceding the release you are going to make.

In this method, if you are about to release version 4.6 but you want to do a pretest first, call it 4.5.90. If you need a second pretest, call it 4.5.91, and so on. If you are really unlucky and ten pretests are not enough, after 4.5.99 you could advance to 4.5.990 and so on. (You could also use 4.5.100, but 990 has the advantage of sorting in the right order.)

Another method is to attach a date to the release number that is coming. For a pretest for version 4.6, made on Dec 10, 2002, this would be 4.6.20021210. A second pretest made the same day could be 4.6.20021210.1.

For development snapshots that are not formal pretests, using just the date without the version numbers is ok too.

A third method, if the package uses Git, is to run the script build-aux/git-version-gen from Gnulib to generate test release version numbers. It generates version numbers in the form ‘version.commits-commithash’, where version is the latest version tag, commits is the number of commits since that tag, and commithash is a hash code for the latest commit.

One thing that you should never do is to release a pretest with the same version number as the planned real release. Many people will look only at the version number (in the tar file name, in the directory name that it unpacks into, or wherever they can find it) to determine whether a tar file is the latest version. People might look at the test release in this way and mistake it for the real release. Therefore, always change the number when you release changed code.

12.6 Automated FTP Uploads

In order to upload new releases to ftp.gnu.org or alpha.gnu.org, you first need to register the necessary information. Then, you can perform uploads yourself, with no intervention needed by the system administrators.

The general idea is that releases should be cryptographically signed before they are made publicly available.

• Automated Upload Registration
• Automated Upload Procedure
• FTP Upload Release File Triplet
• FTP Upload Directive File
• FTP Upload Directory Trees
• FTP Upload File Replacement
• FTP Upload Standalone Directives
• FTP Upload Directive File - v1.1
• FTP Upload Directive File - v1.0

version: 1.2
directory: foo
filename: foo-1.0.tar.gz
comment: let's hope this works!

version: 1.2
directory: foo/foo-1.0
filename: foo-1.0.tar.gz
comment: creates per-version subdirectory as needed

replace: true
version: 1.2
directory: foo
filename: README
comment: replaces an existing README

version: 1.2
directory: foo
symlink: foo-1.1.tar.gz foo-latest.tar.gz
comment: create a symlink

version: 1.2
directory: foo
rmsymlink: foo-latest.tar.gz
comment: remove a symlink

version: 1.2
directory: foo
archive: foo-1.1x.tar.gz
comment: archive an old file; it will not be
comment: publicly available any more.

directory: bar/v1

12.7 Announcing Releases

When you have a new release, please make an announcement. For official new releases, including those made just to fix bugs, we strongly recommend using the (moderated) general GNU announcements list, info-gnu@gnu.org. Doing so makes it easier for users and developers to find the latest GNU releases. On the other hand, please do not announce test releases on info-gnu unless it’s a highly unusual situation.

Please also post release announcements in the news section of your Savannah project site. Here, it is fine to also write news entries for test releases and any other newsworthy events. The news feeds from all GNU projects at savannah are aggregated at https://planet.gnu.org (GNU Planet), unless the text of the entry contains the string ‘::noplanet::’. You can also post items directly, or arrange for feeds from other locations; see information on the GNU Planet web page.

You can maintain your own mailing list (typically ‘info-package@gnu.org’) for announcements as well if you like. For your own list, of course you decide as you see fit what events are worth announcing. (See Dealing With Mail, for setting this up, and more suggestions on handling mail for your package.)

When writing an announcement, please include the following:

• A very brief description (a few sentences at most) of the general purpose of your package.
• Your package’s web page (normally ‘https://www.gnu.org/software/package/’).
• Your package’s download location (normally ‘https://ftp.gnu.org/gnu/package/’). It is also useful to mention the mirror list at https://www.gnu.org/order/ftp.html, and that ‘https://ftpmirror.gnu.org/package/’ will automatically redirect to a nearby mirror.
• The NEWS (see NEWS File in GNU Coding Standards) for the present release.

You may find the announce-gen script useful for creating announcements, which is available from the build-aux/ directory of the gnulib project at https://savannah.gnu.org/projects/gnulib.

13.1 Hosting for Web Pages

The best way to maintain the web pages for your project is to register the project on savannah.gnu.org. Then you can edit the pages using CVS, using the separate “web pages repository” available on Savannah, which corresponds to ‘https://www.gnu.org/software/package/’. You can keep your source files there too (using any of a variety of version control systems), but you can use savannah.gnu.org only for your gnu.org web pages if you wish; simply register a “web-only” project.

If you don’t want to use that method, please talk with webmasters@gnu.org about other possible methods. For instance, you can mail them pages to install, if necessary. But that is more work for them, so please use Savannah if you can.

Please note that the GNU webmasters may fix technical details in your web pages (HTML, CSS, obvious typos, broken links in the footer, etc.) and inform you of the change afterwards.

If you use Savannah, you can use a special file named .symlinks in order to create symbolic links, which are not supported in CVS. For details, see https://www.gnu.org/server/standards/README.webmastering.html#symlinks.

13.2 Freedom for Web Pages

If you use a site other than www.gnu.org, please make sure that the site runs on free software alone. (It is ok if the site uses unreleased custom software, since that is free in a trivial sense: there’s only one user and it has the four freedoms.) If the web site for a GNU package runs on nonfree software, the public will see this, and it will have the effect of granting legitimacy to the nonfree program.

If you use multiple sites, they should all follow that criterion. Please don’t link to a site that is about your package, which the public might perceive as connected with it and reflecting the position of its developers, unless it follows that criterion.

Please make sure it is possible to use the web site fully using the Lynx browser, and with the IceCat browser with LibreJS enabled. It should work both with Tor and without Tor. Of course, it is desirable for the site to support as many other browsers as possible.

Historically, web pages for GNU packages did not include GIF images, because of patent problems (see Ethical and Philosophical Consideration). Although the GIF patents expired in 2006, using GIF images is still not recommended, as the PNG and JPEG formats are generally superior. See https://www.gnu.org/philosophy/gif.html.

Please make sure that any Javascript code in your web pages is covered by a free license, and has its license indicated in a way LibreJS can recognize. See https://gnu.org/philosophy/javascript-trap.html. If the Javascript in the page is minified, or for any other reason is not the source code, it must point to its source code as described there.

13.3 Manuals on Web Pages

The web pages for the package should include its manuals, in HTML, DVI, Info, PDF, plain ASCII, and the source Texinfo. All of these can be generated automatically from Texinfo using Makeinfo and other programs. If the Texinfo itself is generated from some other source format, include that too.

When there is only one manual, put it in a subdirectory called manual; the file manual/index.html should have a link to the manual in each of its forms.

If the package has more than one manual, put each one in a subdirectory of manual, set up index.html in each subdirectory to link to that manual in all its forms, and make manual/index.html link to each manual through its subdirectory.

See the section below for details on a script to make the job of creating all these different formats and index pages easier.

We would like to list all GNU manuals on the page https://www.gnu.org/manual, so if yours isn’t there, please send mail to webmasters@gnu.org, asking them to add yours, and they will do so based on the contents of your manual directory.

• Invoking gendocs.sh

https://git.savannah.gnu.org/cgit/gnulib.git/tree/build-aux/gendocs.sh
https://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/gendocs_template

https://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/gendocs_template_min

gendocs.sh --email yourbuglist yourmanual "GNU yourmanual manual"

cd .../texinfo/doc
# download gendocs.sh and gendocs_template
gendocs.sh --email bug-texinfo@gnu.org texinfo "GNU Texinfo manual"

cd .../texinfo/doc
gendocs.sh --email bug-texinfo@gnu.org -o texinfo texinfo "GNU Texinfo manual"
gendocs.sh --email bug-texinfo@gnu.org -o info info "GNU Info manual"
gendocs.sh --email bug-texinfo@gnu.org -o info-stnd info-stnd "GNU info-stnd manual"

gendocs --texi2html -o texinfo texinfo "GNU Texinfo manual"

13.4 CVS Keywords in Web Pages

Since www.gnu.org works through CVS, CVS keywords in your manual, such as $Log$, need special treatment (even if you don’t happen to maintain your manual in CVS).

If these keywords end up in the generated output as literal strings, they will be expanded. The most robust way to handle this is to turn off keyword expansion for such generated files. For existing files, this is done with:

cvs admin -ko file1 file2 ...

For new files:

cvs add -ko file1 file2 ...

See the “Keyword Substitution” section in the CVS manual, available from https://cvs.nongnu.org.

In Texinfo source, the recommended way to literally specify a “dollar” keyword is:

@w{$}Log$

The @w prevents keyword expansion in the Texinfo source itself. Also, makeinfo notices the @w and generates output avoiding the literal keyword string.

17.1 Free Software and Open Source

The terms “free software” and “open source”, while describing almost the same category of software, stand for views based on fundamentally different values. The free software movement is idealistic, and raises issues of freedom, ethics, principle and what makes for a good society. The term open source, initiated in 1998, is associated with a philosophy which studiously avoids such questions. For a detailed explanation, see https://www.gnu.org/philosophy/open-source-misses-the-point.html.

The GNU Project is aligned with the free software movement. This doesn’t mean that all GNU contributors and maintainers have to agree; your views on these issues are up to you, and you’re entitled to express them when speaking for yourself.

However, due to the much greater publicity that the term “open source” receives, the GNU Project needs to overcome a widespread mistaken impression that GNU is and always was an “open source” activity. For this reason, please use the term “free software”, not “open source” or “FOSS”, in GNU software releases, GNU documentation, and announcements and articles that you publish in your role as the maintainer of a GNU package. A reference to the URL given above, to explain the difference, is a useful thing to include as well.

17.2 GNU and Linux

The GNU Project was formed to develop a free Unix-like operating system, GNU. The existence of this system is our major accomplishment. However, the widely used version of the GNU system, in which Linux is used as the kernel, is often called simply “Linux”. As a result, most users don’t know about the GNU Project’s major accomplishment—or more precisely, they know about it, but don’t realize it is the GNU Project’s accomplishment and reason for existence. Even people who believe they know the real history often believe that the goal of GNU was to develop “tools” or “utilities”.

To correct this confusion, we have made a years-long effort to distinguish between Linux, the kernel that Linus Torvalds wrote, and GNU/Linux, the operating system that is the combination of GNU and Linux. The resulting increased awareness of what the GNU Project has already done helps every activity of the GNU Project recruit more support and contributors.

Please make this distinction consistently in GNU software releases, GNU documentation, and announcements and articles that you publish in your role as the maintainer of a GNU package. If you want to explain the terminology and its reasons, you can refer to the URL https://www.gnu.org/gnu/linux-and-gnu.html.

To make it clear that Linux is a kernel, not an operating system, please take care to avoid using the term “Linux system” in those materials. If you want to have occasion to make a statement about systems in which the kernel is Linux, write “systems in which the kernel is Linux” or “systems with Linux as the kernel.” That explicitly contrasts the system and the kernel, and will help readers understand the difference between the two. Please avoid simplified forms such as “Linux-based systems” because those fail to highlight the difference between the kernel and the system, and could encourage readers to overlook the distinction.

To contrast the GNU system proper with GNU/Linux, you can call it “GNU/Hurd” or “the GNU/Hurd system”. However, when that contrast is not specifically the focus, please call it just “GNU” or “the GNU system”.

When referring to the collection of servers that is the higher level of the GNU kernel, please call it “the Hurd” or “the GNU Hurd”. Note that this uses a space, not a slash.

For more about this point, see https://www.gnu.org/gnu/gnu-linux-faq.html.