To trace the provenance of specific changes and updates to the Unified Astronomy Thesaurus the UAT project team is using GitHub Issues to track contributions and the decisions made regarding each suggestion and GitHub Releases to capture snapshots of the repository each time a new version is published.
As a lightweight tracking system, GitHub has several prominent features: any user with a free GitHub account can raise an Issue to make a suggestion or contribution, the issue can be assigned to a project member, it can be attached to a Milestone, it can be tagged for filtering, it can host short discussions, and it can be closed once completed.
This guidance document details how the UAT Curator uses the features of GitHub Issues and GitHub Releases to track contributions and updates to the Unified Astronomy Thesaurus.
Issues, Tags, Milestones, and Releases
Those who have suggestions for the UAT are encouraged to create a GitHub account and post it as an Issue to the UAT GitHub project. Suggestions submitted directly to a member of the UAT project team will be added as Issues with information about when it was received and who originally submitted it. It is preferred that separate suggestions be added as separate Issues, to help facilitate discussion and give each contribution a straightforward path to decision.
Each Issue will then be assigned to a UAT project member for follow up and decision making and it will be tagged as a general indication of what kind of suggestion is being made.
If a contribution has been accepted into the UAT, its Issue will be added to the current Milestone by a UAT project member. Once the Issue has been fully implemented into the developmental version of the UAT, the Issue will be closed with a comment indicating the action taken.
If a contribution has been rejected from the UAT, its Issue will be closed with a comment stating the reason for that decision. A rejected contribution will typically have some discussion in its GitHub Issue thread for added detail and clarity to the reasoning behind the decision. These contributions will not be attached to a Milestone.
About a month before the next scheduled release of the UAT, the Issues will no longer be added to the current Milestone. This gives project members time to complete work on all remaining open Issues under the Milestone and to check the UAT for errors. Once all issues are closed, the Milestone will also be closed with comment to indicate the version number of the new release.
The release notes of the new UAT version on GitHub will include a summary of changes and a link to the closed Milestone, so that issues resolved by the release can be seen in detail and easily browsed.