update documentation to more clearly discourage use of this plugin

[travi]

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

[seebeen]

Working on it 😊

[sheerlox]

As I generally want my git repository to be the source of truth for everything, I highly value having my version number in package.json up-to-date, and I also prefer using a CHANGELOG over GitHub releases: these features were even what brought me to semantic-release ~ 5 years ago since the company I worked at was not publishing anything to NPM, but we were loading the version number from package.json in our codebases for reporting purposes (debugging/monitoring and displaying to end-users), and we also used CHANGELOGs as references for technical, management and end-users reporting on development progress.

Keeping a CHANGELOG is generally a good standard, is platform-independent, and also has the benefit of being searchable directly from the IDE.

Fwiw I think it would be better to focus on:

• improving documentation on the current state of authentication and tackling the security issues currently at hand, possibly with a GitHub App and repository rulesets, see Update docs for fine-grained GitHub tokens #509
• if releasing multiple packages from the same repository is a concern, adding explicit support for monorepos could be an excellent feature to add, e.g. pushing only one release commit. Probably basing work on the way lerna is working. Work to achieve a similar behavior had been done a few years ago at atlassian/lerna-semantic-release, but it seems they abandoned the project. There is also pmowrer/semantic-release-monorepo, but it's unmaintained and does not work with the ESM versions of semantic-release packages.

[travi]

As I generally want my git repository to be the source of truth for everything, I highly value having my version number in package.json up-to-date

i have to get a little bit pedantic to clarify this detail. in this particular case, the git repository simply isn't the source of truth. it can be a source of mostly reliable information, but in the case of most recent version released, the actual registry is the actual source of truth and other sources, like the git repo, have to be synced with that source to be accurate. semantic-release does a great job under normal circumstances doing that syncing, but it is important to recognize that it isnt actually the source of truth. the reason this is important is that there are some failure scenarios that can leave the two sources out of sync, making the git source misleading and potentially unreliable.

Keeping a CHANGELOG is generally a good standard, is platform-independent, and also has the benefit of being searchable directly from the IDE.

no argument that there are benefits to maintaining a changelog. however, there usually is very little benefit to maintaining a changelog file and release notes in github releases. github releases are enabled by default in core and we dont make it very clear that you should consider disabling the github releases release notes if you choose to use a changelog instead.

• if releasing multiple packages from the same repository is a concern, adding explicit support for monorepos could be an excellent feature to add, e.g. pushing only one release commit.

these are the types of complexities that continue to make us shy away from official support of monorepos, but are also the types of details that we would want to get right if we ever do pursue official support. we currently have no plans to invest in official support in the near or medium term and instead look to our community to expand on our core to support monorepos outside the official org.

in the end, the goal of this issue isnt to deprecate the git or changelog plugins, but instead discourage using them unless you truly want those behaviors in your project and are willing to deal with the extra complexity that is added to your project as a result. the additional complexity from including commits in the release process is significant and we need to at least make it more clear that including them is an important decision point and has tradeoffs worth considering. the added complexity also results in lots of support threads that could be avoided if our docs both made the decision more clear and provided more detailed information for folks that do chose to include commits in their releases despite our warnings.