Skip to content

Files

Latest commit

 Cannot retrieve latest commit at this time.

History

History
149 lines (90 loc) · 11.1 KB

practice.md

File metadata and controls

149 lines (90 loc) · 11.1 KB

Practicing our open source policy

This document is meant to give specific team guidance on putting our open source policy into practice.

18F team members should work with the strong presumption that all of their code will be public, throughout and after development.

Before deciding to delay or withhold the release of source code, consult with the team and be prepared to publicly document this exception.

Public domain

By law, works of the United States government are not copyrightable in the US, and so are public domain. But by default, US government works are copyrightable internationally, and so 18F intentionally waives this copyright abroad using Creative Commons Zero (CC0) 1.0.

There are potentially other cases where copyright is involved: where contractors produce the work, or where work was otherwise originally performed not in the capacity of a US government employee.

To the extent 18F has the rights to do so, 18F will normalize the copyright status of its work product under CC0.

Contributing back to outside projects

18F staff are encouraged to seek existing, open source solutions -- whether government or non-government -- before writing custom tools. When existing libraries need to be modified or improved, 18F staff should make the modifications with eventual upstream contribution in mind.

In practice, this generally involves forking the relevant repository to the 18F organization within GitHub, creating a new branch with the modifications, and sending a pull request to upstream from the 18F fork. Unlike our own projects, there is no need for internal code review in this scenario (though it doesn't hurt).

In terms of licensing: as works of the government, employee contributions are public domain in the United States, regardless of the outside project's contribution agreement. This does not change the overall license status of the outside project.

As the Free Software Foundation says about government-contributed improvements to GPL software:

Yes. If the improvements are written by US government employees in the course of their employment, then the improvements are in the public domain. However, the improved version, as a whole, is still covered by the GNU GPL. There is no problem in this situation.

See also: The Department of Defense's FAQ question about this.

Contributor License Agreements (CLAs)

Some external projects have CLAs. You cannot sign these yourself, in your official capacity.

  1. See if there is an organizational CLA available.
  2. Send the agreement to GSA's Office of General Counsel (OGC) for review.
  3. Collect names/emails/GitHub usernames (whatever is needed) for folks you think will be contributing.
    • Usually easier to add too many than too few.
  4. Get it signed.
  5. Add to list below.
  6. Contribute.

18F currently has the following CLAs signed:

How to license 18F repos

When creating a repo, add a LICENSE.md and CONTRIBUTING.md file, and add/edit the README.md template.

The preceding links are to our standard boilerplate for each of those, so you can just copy and paste them. In some cases, you may need to customize them for your use -- for example, if you've forked a project that originated from outside the government.

You may wish make the following shell aliases

alias insert-license="curl -sO https://raw.githubusercontent.com/18F/open-source-policy/master/LICENSE.md"
alias insert-contrib="curl -sO https://raw.githubusercontent.com/18F/open-source-policy/master/CONTRIBUTING.md"
alias 18f-init="insert-license && insert-contrib && echo 'Licensed.'"

You can then initialize a new 18F repository's license information with:

18f-init

Want to take it even further and create the repo at the same time?

alias create-repo="mkdir \!* && cd \!* && git init ."
alias create-readme="curl -s https://raw.githubusercontent.com/18F/open-source-policy/master/README_TEMPLATE.md -o README.md"
alias create-18f-repo="create-repo \!* && 18f-init && create-readme && sed 's/[Repo Name]/$(/usr/bin/basename $(pwd))/' README.md && git add . && git commit -m 'initial commit'"

Then create a repo and license it with:

create-18f-repo new-project-name

Even if you don't create a repo, it's recommended to use this README.md template that sums up what's going on.

Accepting contributions from the public

Any 18F project can (and should!) accept open source contributions from the public.

Projects can encourage public contributions by:

  • Creating open issues where public help would be especially welcome.
  • Labeling those issues with help wanted so people can scan issues quickly and services can aggregate volunteer opportunities.
  • Asking for contributions, in the README and in other public writing about the project.
  • Providing solid documentation for any project setup process.
  • Being super nice when communicating with volunteers.

As described above, 18F projects are dedicated to the international public domain wherever possible. In this situation, contributors must agree to release their contributions into the international public domain. Projects can inform contributors of this agreement by copying the CONTRIBUTING.md file from this repo into new project repos, and copying the "Public domain" section of this repo's README into the new project's README.

When an 18F project has a non-standard license status (e.g. it's a fork of a previously licensed project, or is a module/plugin for a GPL project), then that project needs to figure out an appropriate contributing agreement.

Working in public

18F believes in working in public. It creates a healthier working environment, a more collaborative process, and just better software.

All 18F team members are expected to make new source code repositories public from the time of creation. This means we often publish drafts in our repos that may change substantially. If you're interested in learning more about the contents of a repo, email 18F@gsa.gov and we'll direct you to the right person or team.

Protecting sensitive information

There are several types of information that should not be included in open source repositories. See the TTS Handbook for how to handle sensitive information.

Private repositories

If the 18F Infrastructure team determines that a repository should not be public, as described in the open source policy, the reasoning should be documented and a link to that reasoning provided in the repository's README to preserve that knowledge and so the decision can be revisited in the future if circumstances change. If the underlying reasons for making the repository private are not themselves sensitive, this explanation can be placed directly in the README.

Managing 18F resources

18F intends to produce great software for the American people. That means not just rushing through projects to get them working as fast as possible, but managing technical debt with an eye towards usability and reusability.

If a refactoring or feature makes the tool easier for 18F to use in its work, and the teammate doing it is otherwise meeting their duties, then that's time well spent for 18F and the taxpayer.

Open source projects can — and hopefully do! — get use and uptake from outside 18F. It's also okay for individual teammates to create projects they intend to use both at 18F and in their personal capacity.

Teammates do not need permission to start new open source projects in the 18F GitHub organization. However, generally speaking, these projects should have some work applicability.

When creating new open source projects:

  • If you're creating a repo because it's primarily for your 18F work, and the work you perform in it is primarily to benefit 18F, start the repo's life in the 18F organization. It's okay if you also think it'll be helpful in personal work.
  • If you're creating a repo that isn't primarily for 18F work, but you think will likely see use at 18F, start it in your personal account. If you don't have strong feelings or concerns about ownership, consider releasing the project under CC0 to save yourself even having to ever think about it.

As people open issues and request features (no matter whether the repo is in your account or 18F's), continue to exercise professional judgment about how to spend 18F time.

If you think something will benefit 18F and is worth the time, then that's valuable 18F work. If it won't benefit 18F but makes the library better for other uses, that may best be done with personal time.

Archiving a repository

When a repository is no longer useful, it should be archived. This may be because the work has been incorporated into another repository, the project is unmaintained and out-of-date, or some other reason. In order to preserve repository metadata like pull request discussions and issues, the repository should not be deleted or made private.

Exceptions

18F currently has no projects for which we will not ever release the source code. 18F has two projects where source code will be released at a later time:

  • login.gov - The infrastructure code was created in private repositories, though much of their other code is open source.
  • US Citizenship & Immigration Services - Project agreement pre-dated the creation of 18F's open source policy. 18F will work with USCIS to coordinate publication of source code as components are publicly released. Components based on existing open source projects will remain open throughout development.