feat: implement foundations section#14
Conversation
…iguration to new foundation docs
…tation from semantic-release/semantic-release#3264 Co-authored-by: travi <126441+travi@users.noreply.github.com>
Co-authored-by: Copilot <copilot@github.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…le overview and optional steps
…uration documentation
…ks and improved descriptions
…clarity and recommendations
travi
left a comment
travi
left a comment
There was a problem hiding this comment.
this is great! this clarifies a number of concepts that have ben on my radar to improve for some time. really appreciate the effort to get this all clarified to this level!
| Even if this is a strategy that you find useful for the applications you are building, [the original author of the git-flow branching model recommends against it](https://nvie.com/posts/a-successful-git-branching-model/) for that context, | ||
| we do not recommend this long-lived branch orchestration pattern when releasing artifacts with **semantic-release**. | ||
| While the [same reflection](https://nvie.com/posts/a-successful-git-branching-model/) that recommends against using git-flow for web apps suggests that it may still be a good fit for explicitly versioned software, | ||
| **semantic-release** is built with Continuous Deployment/Release in mind instead. |
There was a problem hiding this comment.
an opportunity to expand this section could be to help build the mental model that the act of releasing a library version and consuming it elsewhere, even if that place uses gitflow, specifically enables avoiding gitflow for the library. at a high-level, verify that the library has the intended behaviors in its isolated context and release a stable version based on that confidence. if consuming that version into a consumer, regardless of the consuming project's workflow, exposes a defect, simply fix the defect in the library, test that the fix is effected in the isolated context of the library, and release the fix version.
There was a problem hiding this comment.
Okay, this one is going over my head for now 😅. I'll ask question about it momentarily.
There was a problem hiding this comment.
no worries at all. i'll expand on some context that hopefully can help.
many teams that want to use gitflow with semantic-release dont follow testing practices that enable them to have confidence that their library works in isolation. therefore, in order to have confidence that it works, they want to follow a workflow that enables them to release test versions that they can pull into their consuming projects and test the library behaviors in the context of that consuming project.
semantic-release explicitly does not provide a testing workflow (which is another topic that we should work into these updates more explicitly). often, the teams with the desire to follow gitflow find our pre-release workflow and understand it as a testing workflow, which is not the intent. instead, the pre-release workflow is intended for releasing versions that are not consumable yet for all consumers, usually because the maintainers are working through interface changes that they are unsure about the intended behaviors yet and need feedback from early adopter consumers. that distinction can seem nuanced, but the key difference is that the folks targeting gitflow know the intended behavior they are targeting. they just dont have the practices in place in their context to verify that the intended behaviors are present. this is what i mean by the purpose of the pre-release workflow being distinct from a testing workflow
still happy to talk through additional questions, but that is key context for this
…w configuration documentation
…odels documentation
2 participants
This pull request introduces a new "Foundations" section to the documentation, reorganizing and expanding core conceptual content for semantic-release. Key concepts such as release workflow, plugin architecture, branching strategies, and configuration best practices are now covered in dedicated, discoverable pages. The navigation is updated to reflect this structure, and several new or rewritten docs provide clear explanations of how semantic-release works and how to use it effectively.
Documentation Restructuring and Navigation:
New and Expanded Conceptual Docs:
These changes make the documentation more approachable for new users and easier to navigate for advanced users seeking in-depth explanations of semantic-release's core concepts.
Related Issue