feat: implement foundations section

astro.config.js

@@ -50,9 +50,19 @@ export default defineConfig({
             { slug: "usage/configuration" },
             { slug: "usage/ci-configuration" },
             { slug: "usage/running" },
-            { slug: "usage/plugins" },
-            { slug: "usage/workflow-configuration" },
-            { slug: "usage/shareable-configurations" },
+          ],
+        },
+        {
+          label: "Foundations",
+          items: [
+            { slug: "foundation", label: "Overview" },
+            { slug: "foundation/how-it-works" },
+            { slug: "foundation/steps" },
+            { slug: "foundation/considerations" },
+            { slug: "foundation/supported-branching" },
+            { slug: "foundation/workflow-configuration" },
+            { slug: "foundation/plugins" },
+            { slug: "foundation/shareable-configurations" },
           ],
         },
         {

src/content/docs/foundation/considerations.md

@@ -0,0 +1,54 @@
+---
+title: 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 development)
+
+## What is your primary goal?
+
+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.
+
+:::tip[Recommendation] 
+Adopt **semantic-release** when semantic versioning is your primary objective, with release-step automation as a secondary benefit.
+:::
+
+## 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 of that 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 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.
+
+:::tip[Recommendation] 
+Prioritize semantic versioning for artifacts consumed as dependencies; for directly deployed artifacts, consider using git SHAs instead.
+:::
+
+## 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](/support/faq#it-is-not-needed-for-semantic-release-to-do-its-job)
+and [making commits during the release process adds significant complexity](/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.
+
+:::tip[Recommendation] 
+Keep your configuration minimal and only add release-time commits when there is a clear, justified need.
+:::
+
+## Is the branching strategy of your project supported by **semantic-release**?
+
+Before adopting **semantic-release**, confirm that your team's branching model is compatible.
+
+See [supported branching strategies](/foundation/supported-branching)

src/content/docs/foundation/how-it-works.md

@@ -0,0 +1,61 @@
+---
+title: How it Works
+---
+
+**semantic-release** automates package release workflows by turning commit history into predictable versioning and publishing decisions.
+
+At a high level, it answers three questions on every run:
+
+1. Should a release happen?
+2. If yes, what version should be released?
+3. Where and how should that release be published?
+
+## The core model
+
+When `semantic-release` runs in CI on a configured release branch, it compares commits since the last Git tag and determines release impact from commit semantics.
+
+This relies on a formalized commit message convention. By default, **semantic-release** uses the [Angular Commit Message Conventions](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md), where the type prefix in each commit message signals the impact of that change:
+
+- `fix` commits produce patch releases
+- `feat` commits produce minor releases
+- `BREAKING CHANGE` in a commit footer produces major releases
+
+If no commits since the last release carry a recognized type, no release is published.
+
+Tools like [commitizen](https://github.com/commitizen/cz-cli) and [commitlint](https://github.com/conventional-changelog/commitlint) can help contributors author valid commit messages consistently.
+
+For deeper details on commit analysis, release steps, and plugin hooks, see [Release Steps](/foundation/steps/) and [Plugins](/foundation/plugins/).
+
+## Why CI is central
+
+The release command is designed to run in CI after successful builds. This keeps releases deterministic and removes manual, error-prone release actions.
+
+Each push or merge to a release branch can trigger a release run. Whether that run publishes depends on commit analysis, branch configuration, and plugin behavior.
+
+For setup guidance, see [CI Configuration](/usage/ci-configuration/) and [Getting Started](/usage/getting-started/).
+
+## What drives release behavior
+
+Release behavior is determined by a small set of inputs:
+
+- Commit history since the last release tag
+- Branch configuration (release, maintenance, pre-release)
+- Plugin pipeline and plugin options
+- Credentials available in the CI environment
+
+Those inputs produce outputs such as:
+
+- The next semantic version
+- Release notes
+- Git tags
+- Published artifacts or channels (for example npm dist-tags)
+
+See [Release Workflow Configuration](/foundation/workflow-configuration/) and [Supported Branching Models](/foundation/supported-branching/) for branching behavior.
+
+## Safety and constraints
+
+**semantic-release** is intentionally opinionated. It prioritizes consistent semantic versioning and continuous delivery/release workflows over manual or ad hoc processes.
+
+That means it may refuse to publish when conditions are invalid, such as version conflicts across branches, missing release branches, or failed verification steps.
+
+Read [Considerations](/foundation/considerations/) before designing a workflow that diverges from these assumptions.

src/content/docs/foundation/index.mdx

@@ -0,0 +1,51 @@
+---
+title: Foundations
+---
+
+import { CardGrid, LinkCard } from "@astrojs/starlight/components";
+
+Learn the concepts, constraints, and mental models that make **semantic-release** work.
+
+<CardGrid>
+  <LinkCard 
+    title="How it Works" 
+    href="/foundation/how-it-works/"
+    description="Start with the high-level release lifecycle and how the system fits together."
+  />
+
+<LinkCard
+  title="Release Steps"
+  href="/foundation/steps/"
+  description="Learn what happens at each release step and why order and execution matter."
+/>
+
+<LinkCard
+  title="Considerations"
+  href="/foundation/considerations/"
+  description="Understand the constraints and tradeoffs that shape how semantic-release works."
+/>
+
+<LinkCard
+  title="Supported Branching Models"
+  href="/foundation/supported-branching/"
+  description="Understand which branching strategies are aligned with semantic-release expectations."
+/>
+
+<LinkCard
+  title="Release Workflow"
+  href="/foundation/workflow-configuration/"
+  description="Explore how branch types, channels, and version progression shape release behavior."
+/>
+
+<LinkCard
+  title="Plugins"
+  href="/foundation/plugins/"
+  description="Understand plugin responsibilities and how extension points drive each release step."
+/>
+
+  <LinkCard 
+    title="Shareable Configurations" 
+    href="/foundation/shareable-configurations/" 
+    description="See how teams standardize semantic-release behavior across multiple repositories." 
+  />
+</CardGrid>

src/content/docs/foundation/plugins.md

@@ -0,0 +1,127 @@
+---
+title: "Plugins"
+---
+
+Plugins let `semantic-release` extend release steps through configurable lifecycle methods. Core owns the release lifecycle, exposes lifecycle hooks for selected release steps, and invokes plugin methods bound to those hooks.
+
+This enables support for different [commit message conventions](/foundation/how-it-works/#the-core-model), release note generators, and publishing platforms.
+
+A plugin is a npm module that can implement one or more lifecycle methods for the following hooks:
+
+| Lifecycle Hook     | Related Release Step  | Required | Description                                                                                                                                                    |
+| ------------------ | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `verifyConditions` | Verify Conditions     | No       | Verify conditions necessary to proceed with the release: configuration is correct, authentication tokens are valid, and so on.                                 |
+| `analyzeCommits`   | Analyze Commits       | Yes      | Determine the type of the next release (`major`, `minor`, or `patch`). This hook is required to decide the next release type. If multiple plugins implement `analyzeCommits`, the highest release type returned wins. |
+| `verifyRelease`    | Verify Release        | No       | Verify the parameters of the release that is about to be published, such as version, type, or distribution tag.                                                |
+| `generateNotes`    | Generate Notes        | No       | Generate the content of the release note. If multiple plugins implement `generateNotes`, the release notes will be the concatenation of each plugin output.    |
+| `prepare`          | Prepare               | No       | Prepare the release, for example by creating or updating files such as `package.json`, `CHANGELOG.md`, documentation, or compiled assets and pushing a commit. |
+| `publish`          | Publish               | No       | Publish the release.                                                                                                                                           |
+| `addChannel`       | Add Channel (optional) | No       | Assign the release to a distribution channel when channel management is needed, for example by adding an npm dist-tag.                                         |
+| `success`          | Notify                | No       | Notify consumers or maintainers after a successful release.                                                                                                    |
+| `fail`             | Notify                | No       | Notify consumers or maintainers after a failed release.                                                                                                        |
+
+For each [release step](/foundation/steps/), **semantic-release** runs every plugin in the [`plugins` array](plugins.md#plugins-declaration-and-execution-order) that implements the hook for that step.
+
+Not every release step is hook-backed. For example, core handles `Get Last Release` and `Create Git Tag` directly. `addChannel` is a special-case hook used only when channel management applies.
+
+:::note
+If no plugin with an `analyzeCommits` method is defined `@semantic-release/commit-analyzer` will be used.
+:::
+
+## Plugins installation
+
+### Default plugins
+
+These four plugins are already part of **semantic-release** and are listed in order of execution. They should not be installed separately; installing them independently can result in conflicting behavior if multiple versions are present:
+
+```
+"@semantic-release/commit-analyzer"
+"@semantic-release/release-notes-generator"
+"@semantic-release/npm"
+"@semantic-release/github"
+```
+
+### Additional plugins
+
+Additional plugins should be provided to `npx` with `--package` when running `semantic-release`:
+
+```bash
+$ npx \
+  --package semantic-release \
+  --package @semantic-release/git \
+  --package @semantic-release/changelog \
+  semantic-release
+```
+
+See the [official and community plugins list](/extending/plugins-list) for packages that extend **semantic-release** beyond the default set.
+
+If you want to build your own plugin, see [Plugin development](/developer-guide/plugin/).
+
+## Plugins declaration and execution order
+
+If you need to customize the default plugin set or execution order, configure the [`plugins` option](/usage/configuration/#plugins) by listing plugins by npm module name.
+
+```json
+{
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/npm"
+  ]
+}
+```
+
+:::note
+If the `plugins` option is defined, it overrides the default plugin list, rather than merging with it.
+:::
+
+For each [release step](/foundation/steps/), the plugins that implement that step's lifecycle hook will be executed in the order in which they are defined.
+
+```json
+{
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/npm",
+    "@semantic-release/git"
+  ]
+}
+```
+
+With this configuration **semantic-release** will:
+
+- execute the `verifyConditions` implementation of `@semantic-release/npm` then `@semantic-release/git`
+- execute the `analyzeCommits` implementation of `@semantic-release/commit-analyzer`
+- execute the `generateNotes` implementation of `@semantic-release/release-notes-generator`
+- execute the `prepare` implementation of `@semantic-release/npm` then `@semantic-release/git`
+- execute the `publish` implementation of `@semantic-release/npm`
+
+Order is first determined by release steps (such as `Verify Conditions` → `Analyze Commits`). At each release step, plugins are executed in the order in which they are defined.
+
+## Plugin options configuration
+
+A plugin configuration can be specified by wrapping the name and an options object in an array. Options configured this way will be passed only to that specific plugin.
+
+Global plugin configuration can be defined at the root of the **semantic-release** configuration object. Options configured this way will be passed to all plugins.
+
+```json
+{
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/github",
+      {
+        "assets": ["dist/**"]
+      }
+    ],
+    "@semantic-release/git"
+  ],
+  "preset": "angular"
+}
+```
+
+With this configuration:
+
+- All plugins will receive the `preset` option, which will be used by both `@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator` (and ignored by `@semantic-release/github` and `@semantic-release/git`)
+- The `@semantic-release/github` plugin will receive the `assets` option (`@semantic-release/git` will not receive it and therefore will use its default value for that option)

src/content/docs/foundation/shareable-configurations.md

@@ -0,0 +1,39 @@
+---
+title: "Shareable Configurations"
+---
+
+A shareable configuration is an [npm](https://www.npmjs.com/) package that exports a reusable **semantic-release** configuration object. It lets teams define a common release workflow once and apply it across several projects.
+
+## When to use it
+
+Use a shareable configuration when multiple repositories should follow the same release workflow and only need small project-specific overrides.
+
+In practice, a shareable configuration usually provides the base configuration, while each project keeps only the settings that differ locally.
+
+## How to use it
+
+The shareable configurations to use can be set with the [extends](/usage/configuration/#extends) option, using either an npm package name or a local file path.
+
+```json
+{
+	"extends": "@semantic-release/gitlab-config"
+}
+```
+
+For example, a project can extend a shared base config and still override its own branches locally:
+
+```json
+{
+	"extends": "@semantic-release/gitlab-config",
+	"branches": ["main", "next"]
+}
+```
+
+If multiple shareable configurations are defined, they are loaded in order. Local configuration and CLI arguments take precedence over values defined in a shareable configuration.
+
+## Shareable Configurations list
+
+See the [shareable configurations list](/extending/shareable-configurations-list) for official and community-maintained packages you can extend.
+
+If you want to build your own shareable configuration, see [Shareable configuration development](/developer-guide/shareable-configuration/).
+