Conversation
…e natural setup flow (#4) This pull request updates the "Getting Started" documentation for **semantic-release**, it reorders the steps so that project-level configuration comes immediately after installation, followed by CI setup and authentication. The sidebar menu under "Usage" is updated to match, placing "Configuration" before "CI Configuration" so the navigation tells the same story as the getting-started guide. Additionally, the page is converted from .md to .mdx to leverage Starlight's <Steps> component, and a broken #configuration anchor link is corrected. ### Screenshot/Screencast <img width="1913" height="994" alt="image" src="https://github.com/user-attachments/assets/2b7ca2cb-97a6-4866-9d82-ae04dd9361fa" />
This pull request introduces a new `PluginCard` component and supporting styles to the codebase, laying the groundwork for a more modular and visually appealing presentation of plugin information. Additionally, the previous static Markdown list of plugins has been removed, likely in preparation for a more dynamic or component-based approach. The most important changes are: **Component Addition:** * Added a new `PluginCard.astro` component, which displays plugin information (name, URL, description, and steps) in a styled card format. The component supports expandable sections for each plugin step and includes responsive, accessible design features. ## Screenshot/Screencast [screen-capture (30).webm](https://github.com/user-attachments/assets/c7fce16a-5182-4933-8d3a-6217e0729d81)
…ase" (#8) This pull request updates the documentation to clarify and modernize instructions for running **semantic-release**, shifting the focus from "installation" to "running" with a strong recommendation to use `npx` rather than local installs. It also updates related links and references throughout the docs to reflect this new approach, and reorganizes the getting started steps for clarity. ## Related Issue - Closes #6 ## Screenshot/Screencast [screen-capture---------.webm](https://github.com/user-attachments/assets/16d06764-804b-4efe-b287-cd9d421990b0)
…nsistency (#9) This pull request updates the `configuration.md` documentation to improve clarity, accuracy, and consistency for configuring semantic-release. The changes reorganize the content, enhance formatting, update references and examples, and clarify how to use configuration files and CLI arguments. ### Key documentation improvements: - Added explicit explanations and examples for configuring via CLI arguments, including precedence rules and limitations (e.g., plugin options cannot be set via CLI). - Expanded and clarified the documentation for all main configuration options, including `extends`, `branches`, `repositoryUrl`, `tagFormat`, `plugins`, `dryRun`, `ci`, and `debug`, specifying types, defaults, and CLI argument usage. ## Screenshot/Screencast [screen-capture (31).webm](https://github.com/user-attachments/assets/2ef4494c-29e8-46e1-a6e7-e26e409b2660) --------- Co-authored-by: Matt Travi <126441+travi@users.noreply.github.com>
…ion (#12) This pull request updates the CI configuration documentation for `semantic-release` to provide a clearer, more structured guide for configuring CI services and authentication. The page now directs users to specific CI recipes, clarifies authentication requirements, and improves links and explanations for environment variable setup. ### Notable Changes **Documentation structure and clarity:** * The CI configuration guide (`ci-configuration.md`) now starts with a summary of the two main requirements: running **semantic-release** only after all tests pass, and configuring authentication. It introduces a new "Choose your CI service" section with direct links to our recipes for popular CI services. * The getting started guide (`getting-started.mdx`) step for CI setup has been expanded to reference the new CI recipe section and provide clearer sub-steps for choosing a CI guide, ensuring correct job ordering, and setting up authentication. **Authentication guidance updates:** * Clarified and updated descriptions for environment variables used for repository authentication, including improved guidance for GitHub and GitLab tokens, and updated links to official documentation. * Updated plugin authentication instructions to reference the latest best practices (such as npm trusted publishing), and pointed users to the CI configuration recipes for detailed setup. * Improved cross-referencing throughout the page to direct users to relevant internal documentation for environment variable configuration and authentication setup. ## Related Issue - #11 ## Screenshot/Screencast [screen-capture.webm](https://github.com/user-attachments/assets/b3ef9252-715a-491f-bd99-db842691cc66) --------- Co-authored-by: Copilot <copilot@github.com> Co-authored-by: travi <126441+travi@users.noreply.github.com>
This pull request introduces a new "Foundations" section to the documentation, reorganizing and expanding core conceptual content for **semantic-release**. Key concepts such as release workflow, plugin architecture, branching strategies, and configuration best practices are now covered in dedicated, discoverable pages. The navigation is updated to reflect this structure, and several new or rewritten docs provide clear explanations of how **semantic-release** works and how to use it effectively. **Documentation Restructuring and Navigation:** - Moved core conceptual topics (e.g., plugins, workflow configuration, branching, shareable configurations) from the "Usage" section into a new "Foundations" section in the sidebar navigation. This improves discoverability and groups foundational knowledge together. - Added an index page for the "Foundations" section with cards linking to each foundational topic for easier exploration. **New and Expanded Conceptual Docs:** - Added new pages explaining essential concepts: - "How it Works": High-level overview of the release lifecycle, decision logic, and CI integration. - "Release Steps": Detailed breakdown of each release step, their order, and how plugins participate. - "Considerations": Guidance on when and why to use semantic-release, semantic versioning applicability, and configuration trade-offs. - "Supported Branching Models": Summarizes branching models that align with semantic-release. - "Release Workflow Configuration": Guide on managing and automating complex release workflows. - "Plugins": Comprehensive explanation of plugin lifecycle, configuration, and execution order. - "Shareable Configurations": How to, when and why use reusable semantic-release config packages. These changes make the documentation more approachable for new users and easier to navigate for advanced users seeking in-depth explanations of semantic-release's core concepts. ## Related Issue - Fixes #13 --------- Co-authored-by: travi <126441+travi@users.noreply.github.com>
This PR revamps the GitHub Actions recipe page to be more
action-oriented, easier to scan, and aligned with current
semantic-release security guidance.
### Notable Changes
- Reworked the page flow to be execution-first:
1. Quick start at the top
2. Clear publishing path selection
3. Minimal Node workflow users can copy and run
4. Deeper context and edge cases afterward
- Improved navigation with direct links from quick start to relevant
sections.
- Added a practical pitfalls checklist and a release readiness
checklist.
- Modernized guidance around publishing/auth:
1. Prioritizes trusted publishing (OIDC) and npm provenance
2. Clarifies token behavior and setup expectations
- Updated the commit-during-release guidance:
1. Recommends GitHub App authentication as the preferred approach
2. Adds a minimal GitHub App token example
3. Explicitly discourages PAT usage due to security risk
- Added guidance that the workflow snippet represents a simple/default
release flow and points users to the Running semantic-release docs for
alternate invocation patterns and non-default setups.
## Screenshot/Screencast
[screen-capture
(68).webm](https://github.com/user-attachments/assets/f676ef37-6223-4305-bbf3-c748e42cbc72)
---------
Co-authored-by: Matt Travi <126441+travi@users.noreply.github.com>
This pull request focuses on improving documentation consistency and navigation by updating internal links to use absolute paths, clarifying section labels, and renaming files for better clarity. It also updates the sidebar configuration and corrects several references throughout the docs to ensure users are directed to the correct and current resources. **Navigation and Sidebar Improvements:** - Updated sidebar labels and slugs in `astro.config.js` for clarity, including renaming `"foundation/steps"` to `"foundation/release-steps"` and adding "Overview" labels to key sections. [[1]](diffhunk://#diff-bcc58cc8f3382abb7f62bf2fffe90990388d4e738c4497ab1f87c55d1ba5d4b1L60-R60) [[2]](diffhunk://#diff-bcc58cc8f3382abb7f62bf2fffe90990388d4e738c4497ab1f87c55d1ba5d4b1L95-R102) **File Renaming and Section Titles:** - Renamed `steps.md` to `release-steps.md` and adjusted section headers for better alignment with terminology. **Documentation Link Updates (Relative to Absolute):** - Updated numerous internal documentation links from relative to absolute paths throughout the documentation, including introduction, JS API, plugin, and CI/CD guides, to improve navigation and prevent broken links. [[1]](diffhunk://#diff-3aa7c93704623b89353ffe9a550a55b35854b634e57ad0d880de365670ce7959L77-R87) [[2]](diffhunk://#diff-3aa7c93704623b89353ffe9a550a55b35854b634e57ad0d880de365670ce7959L135-R135) [[3]](diffhunk://#diff-b4b0332640fee3e1ce23aa232bdaf00f772547b72bc8d289525386e71f1ad44fL25-R22) [[4]](diffhunk://#diff-b4b0332640fee3e1ce23aa232bdaf00f772547b72bc8d289525386e71f1ad44fL37-R31) [[5]](diffhunk://#diff-b4b0332640fee3e1ce23aa232bdaf00f772547b72bc8d289525386e71f1ad44fL59-R55) [[6]](diffhunk://#diff-b4b0332640fee3e1ce23aa232bdaf00f772547b72bc8d289525386e71f1ad44fL84-R80) [[7]](diffhunk://#diff-47a74d652c153a8610b3751295f7b499c1f8229140683701b71e3ae484a46c6aL7-R9) [[8]](diffhunk://#diff-31242370a5bdbd9ea7ed8a308772c80d141551880d5e0fde12b1e37c27178973L7-R7) [[9]](diffhunk://#diff-31242370a5bdbd9ea7ed8a308772c80d141551880d5e0fde12b1e37c27178973L19-R25) [[10]](diffhunk://#diff-31242370a5bdbd9ea7ed8a308772c80d141551880d5e0fde12b1e37c27178973L59-R59) [[11]](diffhunk://#diff-31242370a5bdbd9ea7ed8a308772c80d141551880d5e0fde12b1e37c27178973L91-R91) [[12]](diffhunk://#diff-b0ccac11e5c8c0d372594c6d9302214290aa66659a2b4b314480134ac4ad178fL7-R15) [[13]](diffhunk://#diff-b0ccac11e5c8c0d372594c6d9302214290aa66659a2b4b314480134ac4ad178fL53-R53) **Content and Reference Corrections:** - Fixed references to the renamed release steps section in various docs and plugin pages for accuracy. [[1]](diffhunk://#diff-f7639b6d70cde2af17ed72a16ed708da9c012620f81a4e4401f9aa5c2ee10d0cL27-R27) [[2]](diffhunk://#diff-39085e27a6d0c7deba33776630341eba68f67adcc258a6b418c528c762306875L18-R18) [[3]](diffhunk://#diff-192ad9d1c8699c134c622ec55cfdcadd6dcd9e5a336a8018b3d6e4c10be29d64L23-R23) [[4]](diffhunk://#diff-192ad9d1c8699c134c622ec55cfdcadd6dcd9e5a336a8018b3d6e4c10be29d64L78-R78) **Minor Content Cleanup:** - Removed redundant or outdated badges and introductory content from `intro.md` for a cleaner presentation. These changes collectively enhance the usability and maintainability of the documentation.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
babblebey
commented
Jun 5, 2026
Member
yes, please avoid squashing since we want to maintain history. i dont follow the local rebase comment since i think a normal merge likely covers the need |
travi
approved these changes
Jun 5, 2026
Member
Author
Yea, don't mind me, I over thought the flow haha 😃 .... I had something else on mind |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces several improvements to the documentation structure and adds a new
PluginCardcomponent. The navigation inastro.config.jsis reorganized for better clarity, including the addition of a new "Foundations" section and improved labeling for overview pages. ThePluginCardcomponent provides a reusable UI element for displaying plugin information and steps. Additionally, the JS API documentation is updated for more accurate and consistent internal linking.Documentation Structure Improvements:
astro.config.jsby introducing a new "Foundations" section and moving related items (such as plugins, workflow configuration, and shareable configurations) under it. The "Usage" section is now more focused, and a new "running" page is added.Component Additions:
PluginCard.astrocomponent that displays plugin information, including name, URL, description, and detailed steps. The component features expandable sections for each step and improved styling for better usability.Documentation Link Fixes:
js-api.md) to use consistent hash-based anchors and corrected references to configuration and plugin documentation for improved accuracy. [1] [2]