SemVer management, commits, and MAJOR release policy

[blackfalcon]

Discussion on SemVer Usage

This document discusses the proper use of Semantic Versioning (SemVer) as described in the standard and how our team will apply this standard when making decisions for MAJOR and MINOR releases.

For reference, please review the SemVer Specification. This serves as foundational support for our use of Semantic Release along with Conventional Commits. This is also outlined in our general use Contributing Guidelines.

Problem

Proper use of SemVer is crucial for clear and consistent communication of updates to our consumers. There has been an increase in incorrectly applied Conventional Commits, causing a ripple effect across the ecosystem.

Recommendation

Consumers of Auro should have clear expectations regarding the nature of a release based on the SemVer release tag. Each type of release has associated levels of complexity, and improper use of these levels negatively impacts our users.

Clarity on Patch Updates

Patch (0.0.1) updates should only be used for bug fixes and performance updates. It is essential to be clear about the intent of these updates and avoid incorrect labeling. Any update that adds clarity or improves element or code performance should be committed with a perf: prefix. This ensures that we communicate that this code change does not add a feature and is not correcting defective code.

Only when there is a clearly identified issue with code not performing as expected should we use the bug: prefix.

Clarity on Minor Updates

Minor or feature (0.1.0) updates should only be used for new code that adds a new backward-compatible, customer-facing (public API) feature. This should not apply to tests, internal features, refactoring, updating build processes, etc. Additional updates can be committed to the repository for the next release but should not be labeled as feat:. The optional scope reference in the commit message can be used to tie different comment types to a single feature within the scope of a release.

Please refer to our commit message guidelines for examples.

Clarity on Major Updates

Major releases (1.0.0), using the BREAKING CHANGE comment in Semantic Release, SHOULD only be used when introducing backward-incompatible changes to the public API. This action should not be taken lightly, as Major releases can have widespread effects on the entire ecosystem of tools, plugins, and integrations that interact with the software. Developers of these ancillary products may need to update their offerings to maintain compatibility.

Releasing a Major update is a significant event that requires careful planning and consideration.

Identifying a Major update MUST be defined, or discussed in the assigned issue's comments to the developer. The breaking change code commit SHOULD include detailed information about the change, including reasons and individuals involved in the decision process.

The scope of this change and any mitigation strategies MUST be discussed. All removed features MUST have a preceding deprecation plan. Users MUST be informed about the backward-incompatible update in advance.

By adhering to these guidelines, we can ensure a smoother transition and better communication with our users.

Expected Outcomes

Implementing the recommended approach to the proper use of SemVer and Conventional Commits is expected to yield several positive outcomes:

1. Enhanced Clarity and Consistency

   • Improved Communication: Clearer updates for consumers.
   • Reduced Confusion: Less ambiguity about release changes.

2. Increased Efficiency for Developers

   • Streamlined Processes: Clearer commit labeling reduces errors.
   • Focused Development: Prioritized and properly managed updates.

3. Ecosystem Stability

   • Compatibility Assurance: Maintained compatibility across tools and integrations.
   • Developer Preparedness: Ancillary developers are better prepared for changes.

4. Improved Release Quality

   • Reduced Errors: Higher quality releases with fewer mislabelings.
   • Clear Documentation: Better support for users and developers during transitions.

5. Enhanced Feedback Loop

   • User Feedback: Better user feedback leads to continuous improvement.
   • Stakeholder Engagement: Comprehensive planning involves all perspectives.

6. Mitigation of Risks

   • Planned Deprecation: Gradual transition away from deprecated features.
   • Risk Management: Preemptive issue identification and mitigation.

By following these recommendations, the team can expect to achieve a more structured, transparent, and effective release process, ultimately benefiting both the development team and the end users.

[blackfalcon]

In addition to the requirements for SemVer, we need to standardize the use of Pull Request templates better. The following are some key points to address.

1. The PR title - the PR title MUST be descriptive of the related work. E.g. things like bug fixes or updates are not acceptable.
2. The issue or issues that this PR resolves MUST be added to the content of the PR.
3. The PR summary MUST be addressed.

The PR Summary

A reviewer should not have to research or assume what the scope of the PR is. Providing this summery is key for the reviewer to understand how to review and test this PR.

Additionally, the summary SHOULD include a test process so that the reviewer has a clear expectation.

The code commits

For each code commit, the following is expected.

1. A clear title (limit 72 characters) using an imperative mood that meets the specification defined in the Auro Contributing Guidelines. This defines the WHAT of the commit.

Format: prefix(scope): title, issue ID
Example: build(postCss): update the build step to include postCSS #67

2. Each commit SHOULD be accompanied by a clear free-text description of the update. Much like the title is the WHAT, the description defines the WHY. This description has value as this will help inform a future developer or your future self as to why you made the choices you did with the committed update of code.

Example: 8e24c16