opensource.google.com

Menu

Docs

Preparing For Release

go/releasing/preparing

(This is part of the process for releasing Google-owned code as open source. There are different processes for patches and personal projects.)

Google believes in open source and wants to contribute back to the community. At the Open Source Programs Office, it’s our job to help you do that. We want to approve your request! Before requesting approval to release code, you’ll need to do a little prep work for your project.

Name your project

Follow these guidelines specific to open source projects:

  • Use a descriptive name that makes it clear what your project does.
  • Provide a second-choice name in case the first-choice can’t be approved.
  • Don’t use a Google brand (e.g. Google, Android, YouTube) in the name unless it’s a product Google will be promoting.
  • Don’t use “G-Naming” (e.g. Gmail)
  • Don’t use third-party brands except when necessary; use them only as descriptors (e.g. “Test Libraries for Java” rather than “Java Test Libraries”)
  • Don’t name the project after anyone else’s trademarks, no matter how clever it seems.

License your project

The Apache License is Google’s default (it provides us the best legal protections while giving others wide freedom) and you must use it unless there is a specific reason not to, such as:

  • the main audience for your release is a community which has standardized around another license

If you think you need a license other than Apache 2, ask emailremoved@ to confirm this for you.

Package your project

Please be very careful when releasing code — read all the comments to ensure they’re fit for public viewing and ensure the code has no security implications for Google that haven’t been reviewed by the security team. Don’t rely solely on the OSPO team’s review; we will flag any issues we come across, but our primary focus is on licensing and legal issues. We can’t catch every problem.

You must use a third_party directory for any and all code which Google does not own the copyright for. This helps us and downstream users comply with all licensing requirements since the third-party code is easy to find.

Port the build

If your package uses Blaze, you’ll need to ensure it works with Bazel (the externally-available, open source version of Blaze) or convert it to another system. Autoconf is often the best option, but other open source build systems (such as Maven or Ant) are also fine. We offer boilerplate files at //piper/…/boilerplate you may copy for Autoconf / Automake. To see examples of how other projects have handled this, browse projects on https://github.com/google. If you are maintaining code both internally and externally, go/copybara (newer) or go/moe (older, 20% maintained) can help you migrate changes from one repository to the other.

Scrub the comments

Once something is checked into version control, it stays visible in the history even if you delete it later.

  • Remove names and email address of Googlers unless they give explicit permission.
  • Remove confidential information, including references to code names, internal paths / filenames, and internal hosts or IP addresses.

TIP: You do not need to scrub bug numbers or Piper CL numbers

Useful commands:

Show references to *.google.com hostnames, @google.com email addresses, google3, and IP addresses:

egrep -r '\.google\.com|@google\.com|google3?/|([0-9]+\.){3}[0-9]+' <path-to-source-directory>

Show Java/C/C++/Go/Objective C/Objective C++/Swift comments:

find <path-to-source-dir> -type f | egrep '\.(c|cc|h|cpp|go|java|m|mm|swift)' | while read f; do echo "------------ $f ------------------"; sed -n -e '/\/\*.*\*\// {p; b}' -e '/\/\*/,/\*\//p' -e '/\/\//p' "$f"; done

Show Python/Bash comments:

find <path-to-source-dir> -type f | egrep '\.(py|sh)' | while read f; do echo "------------ $f ------------------"; grep -o "#.*" "$f"; done

Include a README file

We want people to actually use code released as open source, so include a README file to help people get started. State plainly what your project does. Show examples. Additional documentation is strongly encouraged in a format of your choosing, but a README file is the minimum you should offer. Many hosts will render Markdown syntax if the file is named README.md.

Include LICENSE file and source code headers

Every file containing source code must include copyright and license information. This includes any JS/CSS files that you might be serving out to browsers. (This is to help well-intentioned people avoid accidental copying that doesn’t comply with the license.)

  • For files in the third_party dir, leave the existing headers in place. If you’ve modified a file, append “Google Inc.” to the copyright line.
  • For Google-authored source files, paste the following Apache header text in the comments at the top. (If you’re releasing under a different license, expand the appropriate zippy section for the header text to use.)

    • This autogen tool written by a Googler makes it easier. For example, to license it as “Google Inc.” with the Apache License, run it as:

      autogen.sh -c "Google Inc." -l apache [filename]
      

(Planning to actively accept outside patches? See the AUTHORS and CONTRIBUTORS page for info about using “Copyright 2014 The [Project] Authors”.)

Apache header

Copyright 2017 Google Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

(Not using the Apache License? We also have other boilerplate available for you to copy.)

There must also be a file named LICENSE in the top-level directory that contains a copy of the license. For the Apache License, simply copy the official 2.0 license into your LICENSE file verbatim (do not edit the Copyright bit template in there, only when you paste that template in the header of your source code files.) If you have approval to use a different license, copy the official license for GNU GPL version 2 or GNU LGPL version 2.1 as appropriate, or copy our BSD license.

Include a CONTRIBUTING file

Here is a basic CONTRIBUTING.md file to get you started:

Feel free to adjust this file to suit your project, including instructions for how you would like people to contribute. Do you prefer that they always open an issue before sending large pull requests? Are there specific test suites or linters they should run? This is the place to mention those.

Next, run this program against your local copy of your repository:

/path/to/.../cross /path/to/.../location

Cross will help you find licensing bits that might not be right, or files with no licenses, or code not copyright Google that should be located in third_party/. It’s not foolproof, and you don’t need to necessarily take action against all messages (i.e. treat messages as warnings, not errors).

There is no need to paste the output of cross into your launch. We will automatically upload a comment to your Ariane launch with the Cross results once you publish your launch.

Stage your code for review

Make your code available on an internal git repository so it can be reviewed by the open source releasing and compliance teams.

Except as otherwise noted, the content of this page is licensed under CC-BY-4.0 license. Third-party product names and logos may be the trademarks of their respective owners.