Add how-to-release guide #97
Conversation
|
Hi @jlamypoirier, I am interested in documenting and setting up a complete release workflow. Can you please review this guide and provide feedback? |
docs/contributing/how-to-release.md
Outdated
|
|
||
| 3. **Versioning Made Simple:** Fast-LLM sticks to [Semantic Versioning](https://semver.org/) (aka semver). Here's the gist: | ||
| - **MAJOR versions** (like `1.0.0`) are for big, stable, feature-complete milestones. Since we're still in pre-1.0 territory, we don't have these yet. | ||
| - **MINOR versions** (e.g., `0.2.0`) bring new features that play nice with existing ones, that don't break anything because of backward compatibility. MINOR releases are the main focus of our current development efforts. They're tied to [milestones](https://github.com/ServiceNow/Fast-LLM/milestones) and are released on a regular schedule. |
There was a problem hiding this comment.
On 0.x we do accept breaking changes
There was a problem hiding this comment.
Agreed. I changed the text accordingly.
docs/contributing/how-to-release.md
Outdated
| 3. **Versioning Made Simple:** Fast-LLM sticks to [Semantic Versioning](https://semver.org/) (aka semver). Here's the gist: | ||
| - **MAJOR versions** (like `1.0.0`) are for big, stable, feature-complete milestones. Since we're still in pre-1.0 territory, we don't have these yet. | ||
| - **MINOR versions** (e.g., `0.2.0`) bring new features that play nice with existing ones, that don't break anything because of backward compatibility. MINOR releases are the main focus of our current development efforts. They're tied to [milestones](https://github.com/ServiceNow/Fast-LLM/milestones) and are released on a regular schedule. | ||
| - **PATCH versions** (e.g., `0.2.1`) squash bugs and tweak small stuff. They don't introduce new functionality. These aren't tied to milestones and drop whenever needed to fix things. |
There was a problem hiding this comment.
Do we really want to bother with those at this point?
There was a problem hiding this comment.
Yes, we absolutely should bother with patch releases. In the past, skipping them forced everyone onto main, leading to frequent disruptions from breaking changes. This caused significant frustration, made it difficult to reproduce results, and created chaos when experiments started with one version of main and broke with the next.
Patch releases provide a stable, reliable option for critical experiments without requiring much additional effort. They are simply tagged, tested commits from main with bug fixes. That's minimal overhead compared to the pain of debugging issues caused by untracked changes. By adopting patch releases, we ensure stability, reproducibility, and smoother workflows for everyone.
There was a problem hiding this comment.
I made some changes to the text to reflect that.
docs/contributing/how-to-release.md
Outdated
|
|
||
| 4. **Milestones are for MINOR Releases:** Each [milestone](https://github.com/ServiceNow/Fast-LLM/milestones) corresponds to a MINOR version (`0.2.0`, `0.3.0`, etc.) and includes all issues and pull requests targeted for that release. Milestones have due dates and are used to track progress toward the next MINOR release. PATCH releases? Handled as individual issues or small groups of issues. | ||
|
|
||
| 5. **All Roads Lead to `main`:** Active development happens on the `main` branch, whether it's for a MINOR or PATCH release. We don't do release branches, backport features, or support old versions. Stick with the latest release for stability. As a user, you are never expected to use `main` for production unless you're ready to live on the edge. |
There was a problem hiding this comment.
What about our internal use? I think it's a good idea to use stable version for important experiments, but we need at least some usage of main to find unforeseen issues. Otherwise we'll just delay the problem and we'll get more issues with each new release that are more annoying and more difficult to address.
There was a problem hiding this comment.
You are absolutely right that main needs internal testing to catch issues early, but relying on it for important experiments has caused significant problems in the past. As you know, we've had many cases where breaking changes in main disrupted experiments, making it impossible to reproduce results or continue training runs. This has led to much frustration and wasted time.
Tagged releases solve this by providing a stable reference point for critical experiments while still allowing main to be tested internally. To prevent past issues, we should recommend using PATCH or MINOR releases for important experiments and reserve main for exploratory work or testing. This approach balances stability and progress.
There was a problem hiding this comment.
I made changes to the text to make it clear that it's necessary to test main.
| 2. Verify that all targeted pull requests are merged. | ||
| 3. Double-check the repo: | ||
|
|
||
| - All tests should pass. |
There was a problem hiding this comment.
Same when merging to main
✨ Description
Adds a guide that explains how we release new versions of Fast-LLM.
🔍 Type of change
Select all that apply:
📝 Changes
Add How-to-Release guide.