Archiving Repositories

Repositories that will no longer be maintained must undergo an end-of-life archival process. When a repository is archived, its issues, pull requests, code, labels, milestones, projects, wiki, releases, commits, tags, branches, reactions, code scanning alerts, comments and permissions become read-only.

Archival of a repository is not a failure, and it is not a bad thing. We archive our repositories to communicate clearly to, and manage the expectations of, current and prospective users and contributors. A unique function of a Federal public sector open source community is that we serve not only as contributors, but as Stewards. Projects are not valuable solely based upon the utility of their results or outputs, they reflect the record of our progress. Archives provide transparency, accountability, and attribution. Archives build trust, reduce duplicate work, and reduce risk. The work we do today, saved in our archived repositories, may allow historians to more accurately and completely understand how our work contributed to the story of our Nation.

Considerations

Based on TODOgroup's guide:
https://github.com/todogroup/guides/blob/master/shutting-down-an-open-source-project.md

• Agency goals have changed
• Key person or team that headed the effort leaves
• Project performance metrics (e.g. participation, usage, adoption, updates) are declining based on your latest user data
• Maintenance status has changed (e.g. code is no longer being patched or updated by the community to resolve vulnerabilities)

Repository Archival Checklist

For all tiers

Review Metadata

In code.json:

• Change status to archival.
• Add archived to tags.
• Review all fields to ensure project metadata is correct and accurate.

Enabling archived mode in the automated-codejson-generator GitHub Action handles this work.

Review Repository

Repository Documentation can provide explicit statements about the status of a project or community. Communicating clearly, whether the project is active or inactive, is important.

Update Repository Documentation

• Clearly state at the top the README that the project has been deprecated and will no longer be updated. If possible, suggest alternate projects that provide similar functionality.
  • Sample Text:

    "This project is now archived and no longer actively maintained. It has been archived to retain its contents for reference. Feel free to explore and fork the repository, but please note that updates or support will not be provided."

Issues

Repository Issues serve as a type of record of the decision making processes of a project, and can provide visibility into project history and intended or recommended future development. Deleting them outright is not recommended.

• Review all issues.
  • Close fixed issues
  • Comment on unresolved issues
  • Label issues
  • Close issues as won't fix where applicable

Repository Access

• Review committer access

Perform a lightweight security review

• Review for secrets, keys, PII

Other

• Delete inactive branches

For Tiers 2-4

Review Repository

Pull Requests

Repository Pull Requests serve as a type of record of the decision making processes of a project, and can provide visibility into project history and intended or recommended future development. Deleting them outright is not recommended.

• Review all pull requests.
  • Merge PRs that have no conflicts and pass all tests
  • Test and merge any Dependabot PRs that don't fail tests
  • Comment on any open PRs
  • Close any 'won't fix PRs where applicable

Documentation

• If distributed via package managers (e.g., npm, PyPI, RubyGems): update with a deprecation warning that clearly states that the project is no longer being maintained or updated.
• Review project board
  • Apply an "archived" label to all columns or cards as necessary
  • Complete or close any open milestones
• Review wiki
  • Add a clear notice to home page about archival status
  • Check each page for completeness. Mark them as incomplete if necessary

Communications

• Review project communication channels
  • Slack, mailing lists, forums, social media, and any other channels used for communication within the project.
  • Marketing and other internal teams should also be notified.
• Known users of the project should also be notified.

Outbounding

• Review code quality
• Review commit history
• Resolve code scanning and security alerts (e.g. Dependabot, CodeQL)
• Ensure CHANGELOG.md outlines completed work and the project's final state
• Review releases and tags (if applicable, Maturity Model Tier3+)

Archiving a repository on DSACMS GitHub

Based on https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories#archiving-a-repository

In the repository's settings page, click on the Archive this Repository button located in the Danger Zone.

Step 1	Step 2

Archiving a repository on CMS-wide GitHub Organizations

To archive a repository on any CMS-wide GitHub Organizations, please submit a ticket to the respective IT Help Desk. The request visibility will be made private by default, so you will need to share with the ticket with project leads to obtain approvals.

CMSgov

Submit a request to the CMS Web Help Service Desk: https://jira.cms.gov/servicedesk/customer/portal/1/create/11

CMS-Enterprise

Submit a request to the 18F only, CMS Enterprise Agile Tools Service Desk: 18F only, https://jiraent.cms.gov/servicedesk/customer/portal/4/create/183