From 3255c2bd41512b185f0bafedc34e4eaa7ef09131 Mon Sep 17 00:00:00 2001 From: Matt Travi Date: Fri, 19 Apr 2024 16:29:26 -0500 Subject: [PATCH] wip(supported-workflows-docs): captured a start to a structure --- SUMMARY.md | 2 + docs/usage/considerations.md | 38 +++++++++++++++++++ docs/usage/supported-branching.md | 61 +++++++++++++++++++++++++++++++ 3 files changed, 101 insertions(+) create mode 100644 docs/usage/considerations.md create mode 100644 docs/usage/supported-branching.md diff --git a/SUMMARY.md b/SUMMARY.md index 2a463bf9a2..58c3de0d1d 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -2,11 +2,13 @@ ## Usage +- [Considerations](docs/usage/considerations.md) - [Getting started](docs/usage/getting-started.md) - [Installation](docs/usage/installation.md) - [CI Configuration](docs/usage/ci-configuration.md) - [Configuration](docs/usage/configuration.md) - [Plugins](docs/usage/plugins.md) +- [Supported Branching Models](docs/usage/supported-branching.md) - [Workflow configuration](docs/usage/workflow-configuration.md) - [Shareable configurations](docs/usage/shareable-configurations.md) diff --git a/docs/usage/considerations.md b/docs/usage/considerations.md new file mode 100644 index 0000000000..d6c792ce99 --- /dev/null +++ b/docs/usage/considerations.md @@ -0,0 +1,38 @@ +# Considerations + +**semantic-release** is + +- an opinionated release tool +- a tool to simplify versioning releases semantically first, automating steps related to a release process second +- a tool that encourages engineering practices that support delivering high quality at a sustainable pace (continuous deployment/release, trunk based deployment) + +## Are you interested in **semantic-release** because of our primary or secondary goals + +If your primary attraction is for automatic release note generation rather than semantic versioning, you may want to reconsider if **semantic-release** is the right fit for your goals. + +## Do you actually need semantic versioning? + +The use of the word "semantic" in the term "semantic versioning" has the intent that the structure of the version conveys specific meaning. +Consult https://semver.org/ for details about the details of the specific meaning, but keep in mind that the semantics are from the perspective of a consumer. + +Semantic versioning is most useful for software releases that are consumed programmatically. +Common examples are libraries/packages consumed as dependencies. +Base Docker images can also fall in this category because they are consumed in a way that other layers build on top of them. + +Applications that are deployed directly to a runtime environment lack an audience to benefit from the benefits of semantic versioning. +Docker images that are published to a registry only for the purpose of deploying directly to a runtime environment fall into this category, even though they are a published asset. +Often, using the git SHA as the version for such assets is a better choice than versioning them semantically. + +## Can you simplify the release steps automated by **semantic-release**? + +Updating the version in the `package.json` of an npm package or providing release notes in a `CHANGELOG.md` file are popular release steps +that can be enabled with **semantic-release** using the [changelog](https://github.com/semantic-release/changelog) and [git](https://github.com/semantic-release/git) plugins. +However, those two plugins are intentionally _not_ included in the default configuration of **semantic-release** because +[they are not necessary for **semantic-release** to function](https://semantic-release.gitbook.io/semantic-release/support/faq#it-is-not-needed-for-semantic-release-to-do-its-job) +and [making commits during the release process adds significant complexity](https://semantic-release.gitbook.io/semantic-release/support/faq#making-commits-during-the-release-process-adds-significant-complexity). + +Please consider the trade-offs of adding those plugins to your release configuration for potentially unnecessary goals. + +## Is the branching strategy of your project supported by **semantic-release**? + +[supported branching strategies](./supported-branching.md) diff --git a/docs/usage/supported-branching.md b/docs/usage/supported-branching.md new file mode 100644 index 0000000000..9484c8b616 --- /dev/null +++ b/docs/usage/supported-branching.md @@ -0,0 +1,61 @@ +# Supported Branching Models + +## Trunk Based Development + +- https://trunkbaseddevelopment.com/ +- https://minimumcd.org/minimumcd/tbd/ + +### Committing Straight to the Trunk + +- https://trunkbaseddevelopment.com/#trunk-based-development-for-smaller-teams +- https://trunkbaseddevelopment.com/committing-straight-to-the-trunk/ + +### Short-Lived Feature Branches + +- https://trunkbaseddevelopment.com/#scaled-trunk-based-development +- https://trunkbaseddevelopment.com/short-lived-feature-branches/ + +### Continuous Integration + +- https://minimumcd.org/minimumcd/ci/ + +### Continuous Deployment/Release + +- https://trunkbaseddevelopment.com/continuous-delivery/#continuous-deployment + +## GitHub Flow + +- https://githubflow.github.io/ +- https://docs.github.com/en/get-started/using-github/github-flow + +## Officially Unsupported Branching Models + +### Trunk Based Development: Branch for release + +https://trunkbaseddevelopment.com/branch-for-release/ + +exception: + +- https://trunkbaseddevelopment.com/branch-for-release/#late-creation-of-release-branches + - our maintenance release is an example of this approach + +### git-flow + +- https://nvie.com/posts/a-successful-git-branching-model/ +- https://jeffkreeftmeijer.com/git-flow/ + +Even if this is strategy that you find useful for the applications you are building, which [the original author of the git-flow branching model recommends against](https://nvie.com/posts/a-successful-git-branching-model/), +we do not recommend this branching model 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. + +While some have found that the [Pre-release workflow](./workflow-configuration.md#pre-release-branches) enabled by **semantic-release** can be used to _simulate_ a git-flow-like workflow, +it is also worth noting that workflow is not intended for such a use case and requests for support when attempting to use it that way will be closed by our team. + +### Workflows that Release for Testing Before Promotion to a Stable Release + +- https://trunkbaseddevelopment.com/styles/#the-importance-of-a-local-build + +### Monorepos + +While not specifically a branching strategy,