Publishing a Release to usds.gov
(This is a work in progress.)
Content additions and changes will make their way to the master branch.
These changes are sent to the official usds.gov site by creating and publishing a GitHub Release.
A GitHub Release has two parts.
- A tag, which is a kind of "bookmark" in the history of changes that GitHub tracks. This defines the exact content of the Release. BTW, tags are used for many purposes besides Releases.
- A title, description, and other metadata about releasing that tag.
This repository is configured so that the contents of a Release are moved to usds.gov when the Release is published.
Click the link to existing Releases on the right side of the repository's main page. (The URL is https://github.com/usds/website/releases).
Click the button labelled Draft a new release. (If you don't see the button, double check that you are at https://github.com/usds/website/releases; it's easy to click the link for one specific Release instead.)
On the new Release page, you must first "choose" a tag. This may be the trickiest part, because GitHub's user interface is a bit confusing here.
1. Click the Choose a tag button and a dropdown appears. The dropdown shows a list of existing tags, along with a text input.
2. Type your new tag name in the dropdown's text box. (See Guidelines for more on tag names). As you type, the page dynamically searches for existing tags that match your input. But in our workflow we don't create the tags ahead of time. When your input is a new name (not used for any existing tags), the text at the bottom of the dropdown will change.
3. Click the Create new tag ... on publish text that appears at the bottom of the dropdown. You should see a small message Excellent! This tag will be created from the target when you publish this release.
Now you fill in all the metadata for the new Release.
1. Enter the Release's title. (See Guidelines for more on Release titles.)
2. Enter a description of the Release.
3. Click the Generate release notes button. This expands the description with auto-generated details about the changes that have been made.
4. Click the green Publish release button at the bottom.
This will start automation that puts the contents identified by the new Release tag onto usds.gov. The process typically takes about 90 seconds.
https://usds.gov/ref.txt displays the tag name for the content that is on the site. When the automation completes, you can refresh this page to see the tag name you created for the newly published Release.
If the new content is problematic, broken, does not render as expected, etc. you can "undo" this process by following this process.
You can check the automation status by clicking the Actions tab near the top of any repo page. A history of automation runs is shown. The top item should have your newly published Release's title. A green checkmark indicates successful completion. A red X indicates a failure. Various yellow icons indicate that the automation is actively running.
Diagnosing and troubleshooting automation problems is beyond the scope of this document.
Tag names must be unique. There is no need to follow the Tagging Suggestions that appear on the GitHub page; they are more relevant to software versioning. Tag names should be relatively brief. Use only letters, numbers, dashes, and periods. Tag names can describe the content, and/or indicate the order of releases by including sequential numbers or dates.
As the word implies, the title of a Release is a human-friendly summary of the Release written in plain English. It may be convenient to include the tag name as part of the Release title.
As the markdown editor on the page indicates, the Release description is a place for information that is as fancy and extensive as you need.
Feel free to attach files to the page for creating Releases. If you wish you can save a draft Release rather than publishing, but the Release contents will not go to usds.gov unless/until the Release is published.
Except for the specific instructions given here, don't change any of the defaults for any of the settings when creating a Release.