semantic-release / semantic-release/git

update documentation to more clearly discourage use of this plugin

Open
#477 3 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
339
Forks
75
Avg merge
5h 15m
Merged PRs (30d)
6

Description

this plugin works great for release workflows that truly need to make commits during the release process, but we want to make it more clear to users that enables releases without the need to make commits. this is the reason why this plugin in not included by default in the core package:

  • some users overvalue having the current version number in the source code repository. semantic-release does not use this value to track the previous version, instead it uses tags. instead it is better to refer to the package registry as the source of truth for which version is currently latest (for example, with npm, npm dist-tags ls is a great way to get this information)
  • some users value maintaining a CHANGELOG.md file over using, for example, github releases. the changelog plugin is also not included by default in the core package to encourage folks to leverage alternatives to maintaining a CHANGELOG file

including commits as part of the release process adds complexities like:

  • working through access issues for pushing commits to release branches with restrictive branch protection rules
  • pulling release commits before being able to push additional changes to the release branch
  • releasing multiple packages from the same repository (officially unsupported by semantic-release) is prevented because the commit resulting from the release of the first package puts the repo in a state where it is behind the latest commit when attempting to release the remaining packages

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No file or test is named in the issue. Locate the plugin documentation describing release commits, revise it to discourage unnecessary commits and explain the registry, tags, GitHub Releases, and commit-related constraints, then verify the documentation reflects the requested guidance.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, javascript
Domain
documentation, release
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.