Maintenance Best Practices

Guidelines

Importing in third party is just the beginning. What you imported is likely here to stay for many years to come, and as an OWNER you have responsibilities. In particular: maintaining the library with newer versions, responding to security issues and patching in a timely manner.

This can be a difficult task, but does not have to be if you follow these best practices:

Automate the import

  • Using tools such as Copybara, Googlify for C/C++, update.go for Go, and others, automate as much as possible the import process
  • Remain careful to only download from the trusted source (e.g. https, signatures when available, etc.); if in doubt contact emailremoved@

Maintain patches

  • It is easy for someone at Google to send a CL and locally modify the source, however next time you have to upgrade the library, this change may be lost.
  • Copybara is the recommended way to handle this. See go/copybara or https://github.com/google/copybara.
  • You are free to use other approaches, such as:
    • Using vendor_src for upgrading your pristine copy, tracking local modifications as piper CLs.
    • storing patches in a patches/ directory and applying them after every import.
  • The important part is that a fresh run of the import and patches should lead to what is on HEAD
  • In other words: every local change is accounted for

Continuous testing

  • Make use of Presubmit, guitar and other tools we use in google3 to keep the library healthy (building, tests passing, etc.) across updates and changes with presubmit checks, etc.

Document

  • It is likely the library has its own quirks, specific maintenance steps, or other things only you know but that might be useful to someone else to maintain it
  • Write a playbook documenting the import process, how one can submit changes, maintain patches, test the library or contact the owners; example: go/libxslt

Stepping down

If you no longer wish to be an owner (e.g. switching teams, not enough time for maintenance, etc.), it is your responsibility to hand-off ownership to someone else.

To find a replacement, ask people who contributed and are familiar with the library or the users and teams depending on the library (go/rdeps). Ask if someone wants to take over ownership, and make sure they know what that means. Share your docs and playbook with potential new owners.

If you cannot find a replacement, the library MUST be deleted from third party: it is the contract per go/thirdparty/responsibilities. It is expected that users and teams depending on the library will step in to take ownership otherwise they would be broken.

Upstream requirements

In order to maintain proper security posture in Google’s products, it is important that the third_party software at Google is actively maintained. While we test third_party code internally for security issues, we must also address external concerns such as CVEs, VRP reports, etc. Failing to address these concerns in a timely matter puts Google, and our users, at risk.

To minimize the risk that this poses, third_party packages which fail to respond to reports of security issues within 180 days will be locked down and considered deprecated. To prevent removal, owners and consumers of the package must either devise a plan to take on maintenance of the project and address the issues, or remove and delete the dependency.