Proposal Rename "Installation" page to better reflect its actual content

[babblebey]

The current "Installation" page (usage/installation.md) is misleadingly titled. The recommended approach on the page is npx semantic-release, which is a run command, npx downloads and executes in a single shot, nothing gets permanently "installed" into the project. The page even explicitly argues against local installation via npm install.

In effect, the page says: "Here's how to install... actually, don't install anything."

What the page actually covers

• The recommended way to invoke semantic-release: npx semantic-release
• Including extra plugins via npx --package
• Version pinning strategies (@25, exact version, Renovate automation)
• Why not to add semantic-release to package.json

This is guidance on how to run semantic-release, not how to install it.

Section-level issues

Current heading	Problem
"Global installation"	npx doesn't perform a global install, it does a temporary download-and-execute instead. The heading contradicts the page's own guidance.
"Local installation"	This section exists only to say "don't do this." It's a discouragement section, not an installation guide.

Proposal

Rename the page and its sections to honestly describe what they cover:

Current	Proposed
Page title: "Installation"	"Running semantic-release"
Section: "Global installation"	"Using npx (recommended)"
Section: "Local installation"	"Local installation (not recommended)"

This would also cascade to the Getting Started page (step 1), where the wording could shift from "Install semantic-release" to something like "Set up semantic-release in your project".

The sidebar slug would also need updating (usage/installation → usage/running), along with any internal links pointing to the old path.

Bigger question: Should this page exist at all?

Looking more closely, the installation page's content is entirely about CI execution:

• npx semantic-release - a command you run in CI
• npx --package ... semantic-release - a CI command with extra plugins
• Version pinning (@25, exact version) - a CI pipeline concern
• Renovate config for auto-updating - CI maintenance
• "Don't install locally" - reinforcing that this is a CI-only tool

Meanwhile, the CI configuration page covers:

• Job ordering (run after tests pass) - CI pipeline structure
• Authentication tokens - CI environment variables

These are two halves of the same page. One says what command to run, the other says when to run it and what credentials it needs. Splitting them forces the user to bounce between two pages to set up what is really a single thing: their CI pipeline.

A merged CI configuration page could look like:

Section	Content
How to run semantic-release	The npx command, --package for extra plugins, version pinning notes (absorbed from installation page)
Run only after all tests succeeded	Job ordering, build stages (existing CI config content)
Authentication	Git tokens, plugin tokens (existing CI config content)

This would also simplify the getting-started flow from 4 steps to 3:

1. Configure semantic-release options and plugins
2. Configure your CI service to run semantic-release with the right job ordering
3. Configure authentication for your Git and package manager repositories

The "don't install locally" note could move to the FAQ (where there's already a "What is npx?" entry it references), or become a small callout within the merged page.

Context

This came up during a broader "reality check" pass over the documentation. The first PR #4 in this series (reorder getting-started steps) already addressed the step ordering and broken anchor links on the Getting Started page.

Questions for maintainers

1. Does "Running semantic-release" feel like the right title, or is there a better alternative? (e.g., "Invoking semantic-release", "Using semantic-release")
2. Should the "Local installation" section be kept at all, or moved to an FAQ/troubleshooting entry instead?
3. Any concerns about changing the URL slug from /usage/installation to /usage/running?
4. Should we go further and merge the installation page into CI configuration entirely? This would eliminate the page, give users one coherent CI setup guide, and reduce the getting-started steps from 4 to 3.

[travi]

great summary. this highlights the evolution of this page and the docs overall. originally, it was about local installation vs global installation, actually encouraging local as the recommended path. later, npx became an option that didnt exist originally. then we started seeing patterns in the support issues that convinced us to start encouraging against local installation and limiting installation to the last responsible moment before release in the CI pipeline. installation originally made sense. i fully agree that it doesnt anymore

• Does "Running semantic-release" feel like the right title, or is there a better alternative? (e.g., "Invoking semantic-release", "Using semantic-release")

"running" is much better than "installation". the one other option that comes to my mind is execution, especially since it aligns with the "x" in npx, but i dont think that would be as approachable

2. Should the "Local installation" section be kept at all, or moved to an FAQ/troubleshooting entry instead?

it still seems to be so common in real usage that i think it needs to be called out as part of setup, but still largely with the goal of discouraging it.

however, there is another reason to keep it there: semantic-release/semantic-release#3955 (comment)

it is a very valid concern that we are recommending against installing in a way that the normal lockfile can pin the entire dependency graph of semantic-release. if it werent for the numerous tradeoffs that come along with that approach, i would prefer that path as well. however, npx is currently the best balance we can recommend for most of our users. i think this tradeoff needs to be presented transparently as part of our setup docs, as was asked for in that thread

3. Any concerns about changing the URL slug from /usage/installation to /usage/running?

nope, i agree that it should be aligned with the title.

maybe not a "concern", but it does bring up a bigger general thought. do we have any solution for redirecting traffic from links to the old pages on the old site? since we will be changing hosts and domains, i think we are pretty limited. maybe that is a reason to not be overly concerned. i dont think we'll have any way of intercepting requests to the old domain. probably need to declare bankruptcy and consider if there is a strategy for future page moves.

4. Should we go further and merge the installation page into CI configuration entirely? This would eliminate the page, give users one coherent CI setup guide, and reduce the getting-started steps from 4 to 3.

i dont think we can get fully to combining them, but i agree that we could improve how complementary the concepts are. we could more strongly reinforce that the intent is to always release from CI and (mostly) never from local. however, i think there is value in a single place for the basics of "this is how you run semantic-release effectively, no matter which CI you are using" and separate guidance for how to do that common thing in the context of the various common CI providers. i think trying to combine those concepts completely muddies both concepts

another current event to consider with how we frame this... we are now encouraging folks to use trusted-publishing when publishing to the official npm registry, which we believe to be the most common use of semantic-release. an important caveat for us to not overlook with this recommendation is that npm does not currently support publishing the first version of a package using trusted publishing. you have to publish an initial version with a granular access token, visit the web interface for that new package, and set up trusted-publishing in the settings. i really hope this situation is temporary, but i havent observed much activity in this space recently.

personally, i use semantic-release locally for that initial publish. i'm wondering if there are parts of the process i normally follow that we should add to the onboarding section. this has been my process lately.

1. scaffold out a new package repo
2. push main to the remote on github
3. create an alpha branch for my initial releases before i'm ready to promote to a stable v1.0.0 (we dont recommend this as obviously as i think we could, so i think this is an opportunity to suggest better)
4. push the alpha branch to the remote on github
5. create a new granular access token for as short of time as possible and as narrow of scope as possible
6. add that token to my local user config (~/.npmrc)
7. run npx semantic-release --no-ci locally in the context of the local repo
8. visit npmjs.com for the new package
9. go to settings and configure trusted-publishing
10. revoke the token that i created since i no longer need it
11. continue pushing commits to alpha until i have a minimal bit of value to release as v1.0.0, confirming semantic-release is fully working as i expect
12. merge alpha to main to promote the prerelease to stable

without the requirement to publish the first version through an alternative path, i was previously able to just do steps 1-4 and then skip to 11

[babblebey]

Great stuff @travi, I think we've reached alignment on the core changes, so here's the plan.....

What we'll do now

1. Rename the installation page to "Running semantic-release"

• Title: "Installation" → "Running semantic-release"
• Sections: "Global installation" → "Using npx (recommended)", "Local installation" → "Local installation (not recommended)"
• Update the slug from usage/installation to usage/running and fix all internal links accordingly

2. Rewrite the "Local installation" section to be transparent about the tradeoff

Instead of just discouraging local install, we'll present both sides honestly, why npx is the recommended balance for most users, and the valid concern that it bypasses lockfile pinning of the full dependency graph. Users deserve to make an informed choice.

3. Update the getting-started steps

The new flow puts "Run semantic-release" last, where it belongs, after all the prep work is done:

1. Configure semantic-release options and plugins
2. Configure your CI service to run semantic-release
3. Configure authentication for your Git and package manager repositories
4. Run semantic-release

This eliminates the old misleading "Install" step that showed a run command before anything was configured.

4. Reorder the sidebar to match: getting-started → configuration → ci-configuration → running → *******

We'll track this separately

npm does not currently support publishing the first version of a package using trusted publishing. you have to publish an initial version with a granular access token, visit the web interface for that new package, and set up trusted-publishing in the settings

I'll open a separate issue to track adding that as maybe a recipe, something like "Publishing your first npm package with trusted publishing." The "Running semantic-release" page can include a brief mention of --no-ci for cases like initial publish, with a link to that recipe.

I'll start on a PR for items 1-4.

[babblebey]

Fixed in #8