1.3. Standards: Milestone Description Guideline

GitHub Milestone Description Guideline

This guide exists to empower teams using GitHub to communicate project progress clearly and effectively. By standardizing the way milestones are described, including the use of semantic versioning, it ensures that everyone involved (developers, project managers, stakeholders) has a shared understanding of the project's trajectory. This leads to better coordination, informed decision-making, and ultimately, a higher likelihood of successful project delivery.

1. Title for Release Milestone (with Semantic Version Tag):

• Use a brief, action-oriented title that summarizes the milestone's core purpose.
• Include a semantic version tag at the beginning of the title. This tag should follow the Major.Minor.Patch/Bugfix format (e.g., 1.2.0, 0.1.3).
• Include repository name in milestone titles to streamline planning.

Examples:

1.0.0 - ut_core: Initial Release

0.3.1 - ut_core: Beta Testing

2.5.0 - ut_core: Major Feature Upgrade.

1.1 Title for Internal Milestone:

• Use a brief, descriptive title that highlights the phased delivery nature of the milestone and its focus on progressively merging code into the main development branch.
• Include the repository name in the milestone title to streamline planning.

Examples:

ut_core: Phased Integration - Part 1

ut_core: Rolling Integration - Feature X

ut_core: Pre-Release Integration

2. Goals (1-3 sentences):

• Explain the "why" behind the milestone. What overall goal does it serve within the project?
• Briefly mention the target audience or impact area if relevant.

Example:

## Goals

This milestone focuses on improving user retention by enhancing the on-boarding experience for new customers.

3. Key Deliverables (Bulleted List)

• List the 3-5 most significant features, functionalities, or outcomes that define the milestone's success.
• Use [ ] - This allows in the github UI to click on tasks completed
• Use clear, specific language that aligns with your project's terminology, this should be the title of your task
• Optionally, link each deliverable to its corresponding GitHub issue or pull request (e.g., "Implement user profile customization (#123)").
• This information (including links), can be mirrored in Project Management Tracking tools, e.g. Jira as User Stores.

Example

## Key Deliverables (Bulleted List)

  * [ ] Implement basic user authentication and authorization (#45)
  * [ ] Build core product functionality for content creation and sharing (#52)
  * [ ] Design and launch initial user interface (#68)
  * [ ] Set up analytics tracking for key user actions (#71)

4. Exit Criteria:

• If applicable, mention measurable targets that will indicate whether the milestone is achieved.
• These could be quantitative (e.g., "Reduce user churn by 15%") or qualitative (e.g., "Positive feedback from beta testers").

Example:

## Exit Criteria

 * At least 50 beta users actively using the platform
 * Positive feedback on core features from at least 75% of beta users

5. Timeline or Due Date:

• Include a target completion date or a general timeframe if known.
• This helps communicate expectations and urgency.
• This should be reflected in the github meta data for the milestone.

Example

## Due Date (GitHub MetaData)

September 30, 2024

6. Additional Notes (Optional):

• Briefly mention any dependencies on external factors, other teams, or specific technologies.
• Highlight any known risks or challenges that might impact the milestone.

Example

## Additional Notes

  * Dependent on completion of API backend by the development team.
  * Potential risk: Limited resources for user testing and feedback collection.

Why Semantic Versioning in Milestone Titles?

• Clear Communication: It instantly signals the stage and scale of the release (major, minor, or patch).
• Organized Tracking: It makes it easy to track the evolution of your project through milestones.
• Consistent Expectations: It sets clear expectations for what kind of changes users can anticipate.

7. Template (Paste-able)

Below is the text that can be pasted in as a template.

GitHub Metadata Fields

• Title: <Semantic Version Tag> - <GitHub Project>: <Milestone Title>
• Due date (optional): dd/mm/yyyy
• Description:

## Goals

*Briefly describe the purpose of the milestone and its impact on the project.*

## Key Deliverables

* [ ] <Deliverable 1> (Issue/PR #)
* [ ] <Deliverable 2> (Issue/PR #)
* [ ] <Deliverable 3> (Issue/PR #)
* [ ] ...

## Exit Criteria

* <Metric 1>
* <Metric 2>
* ...

## Additional Notes (Optional)

### Dependencies

* <Metric 1>

### Risks

* <Metric 1>

### Challenges

* <Metric 1>

### Up-link Data

* **Jira:** <project>-<id>  
    * This Jira issue details the user story that directly aligns with this milestone's goals and deliverables.
    * Include the Jira ID for easy reference and tracking.

Example populated template

GitHub Fields

• Title: 1.0.0 - ut-core: Initial Release
• Due date (optional): 30/10/2024
• Description:

## Goals

This milestone marks the official launch of our product, introducing core features and functionality to the market. 

### Key Deliverables

* [ ] Implement basic user authentication and authorization (#45)
* [ ] Build core product functionality for content creation and sharing (#52)
* [ ] Design and launch initial user interface (#68)
* [ ] Set up analytics tracking for key user actions (#71)

## Exit Criteria

* At least 50 beta users actively using the platform
* Positive feedback on core features from at least 75% of beta users

## Additional Notes:

### Dependencies

* Dependent on completion of API back-end by the development team.

### Risks

* Potential risk: Limited resources for user testing and feedback collection.

### Up-link Data

* **Jira:** RDK-1234