docs: add GitHub Actions guide #1872
Conversation
Aahil13
requested review from
quetzalliwrites,
derberg,
asyncapi-bot-eve and
thulieblack
as code owners
WalkthroughA new documentation file, "Utilizing GitHub Actions," has been added to the onboarding guide. This document provides a detailed explanation of how GitHub Actions are used within the AsyncAPI ecosystem, distinguishing between local and global workflows. It outlines the purposes of various global workflows, the mechanism for synchronizing files across repositories, the use of Semantic Release and Conventional Commits, available slash commands, and the setup steps required for repositories to participate in these automated processes. Changes
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Tip ⚡️ Faster reviews with caching
Enjoy the performance boost—your workflow just got faster. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
Aahil13
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/onboarding-guide/github-actions.md (2)
8-23: Clarify and streamline Table of Contents entries
The TOC includes both Global workflows and Global workflows overview, which might be confusing or redundant. Consider renaming one of these entries for clarity or combining them if they refer to the same content.🧰 Tools
🪛 LanguageTool
[grammar] ~13-~13: This phrase is duplicated. You should probably use “workflows Global” only once.
Context: ...of-github-actions-workflows) - Local workflows - Global workflows - [Global workflows overview](#global-workflows-o...(PHRASE_REPETITION)
95-98: Fix subject–verb agreement in TSC mention description
Change “Notifies the TSC via Slack and email whenever@asyncapi/tsc_membersis mentioned” to “...whenever@asyncapi/tsc_membersare mentioned” to match plural.🧰 Tools
🪛 LanguageTool
[uncategorized] ~97-~97: The verb “is” doesn’t seem to fit in this context, “are” is probably more formally correct.
Context: ... email whenever@asyncapi/tsc_membersis mentioned in issues, PRs, discussions, ...(AI_HYDRA_LEO_CPT_IS_ARE)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/github-actions.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/onboarding-guide/github-actions.md
[grammar] ~13-~13: This phrase is duplicated. You should probably use “workflows Global” only once.
Context: ...of-github-actions-workflows) - Local workflows - Global workflows - [Global workflows overview](#global-workflows-o...
(PHRASE_REPETITION)
[grammar] ~91-~91: It seems that a pronoun is missing.
Context: ...present** in the repository root. | | If Go PR testing | Runs on pull request ...
(IF_VB)
[grammar] ~91-~91: Possible typo detected.
Context: ...f the project contains a go.mod file, it lints and tests the Go code across Linu...
(PRP_VB)
[uncategorized] ~97-~97: The verb “is” doesn’t seem to fit in this context, “are” is probably more formally correct.
Context: ... email whenever @asyncapi/tsc_members is mentioned in issues, PRs, discussions, ...
(AI_HYDRA_LEO_CPT_IS_ARE)
[uncategorized] ~101-~101: “ti” (solization) seems less likely than “it
Context: ... commenting /transfer-issue <repo> or /ti <repo>, validating the target repo fir...
(AI_HYDRA_LEO_CPT_TI_IT)
[uncategorized] ~119-~119: The official spelling of this programming framework is “Node.js”.
Context: ...f-nodejs-pr-testing.yml | Repos withnodejstopic | |replicate_nodejs_releas...
(NODE_JS)
[style] ~132-~132: Consider a more expressive alternative.
Context: ...to trigger it manually for you. To do this, reach out on Slack or open an iss...
(DO_ACHIEVE)
[uncategorized] ~150-~150: The preposition ‘to’ seems more likely in this position.
Context: ...shared workflows, repositories that opt in automatically get support for issue and...
(AI_HYDRA_LEO_REPLACE_IN_TO)
🔇 Additional comments (15)
docs/onboarding-guide/github-actions.md (15)
1-4: Front matter is well-defined
YAML front matter sets the document title and weight correctly.
6-6: Clear and concise introduction
The purpose and scope of the guide are well-articulated.
24-32: TL;DR section is effective
The bullet points succinctly summarize the key takeaways.
33-38: Introduction section reads well
The explanation of GitHub Actions and its importance to AsyncAPI is clear.
39-59: Overview of workflow types is comprehensive
Local and global workflows are clearly distinguished with appropriate examples.
60-71: Global workflows section is informative
Describes the benefits and setup of global workflows accurately.
73-109: Global workflows table is thorough
The table comprehensively lists the available global workflows and their descriptions.🧰 Tools
🪛 LanguageTool
[grammar] ~91-~91: It seems that a pronoun is missing.
Context: ...present** in the repository root. | | If Go PR testing | Runs on pull request ...(IF_VB)
[grammar] ~91-~91: Possible typo detected.
Context: ...f the project contains ago.modfile, it lints and tests the Go code across Linu...(PRP_VB)
[uncategorized] ~97-~97: The verb “is” doesn’t seem to fit in this context, “are” is probably more formally correct.
Context: ... email whenever@asyncapi/tsc_membersis mentioned in issues, PRs, discussions, ...(AI_HYDRA_LEO_CPT_IS_ARE)
[uncategorized] ~101-~101: “ti” (solization) seems less likely than “it
Context: ... commenting/transfer-issue <repo>or/ti <repo>, validating the target repo fir...(AI_HYDRA_LEO_CPT_TI_IT)
91-91: I believe the pronoun usage and sentence structure here is clear and grammatically correct as is.🧰 Tools
🪛 LanguageTool
[grammar] ~91-~91: It seems that a pronoun is missing.
Context: ...present** in the repository root. | | If Go PR testing | Runs on pull request ...(IF_VB)
[grammar] ~91-~91: Possible typo detected.
Context: ...f the project contains ago.modfile, it lints and tests the Go code across Linu...(PRP_VB)
101-101: The slash command alias/tiis intentional; no change needed.🧰 Tools
🪛 LanguageTool
[uncategorized] ~101-~101: “ti” (solization) seems less likely than “it
Context: ... commenting/transfer-issue <repo>or/ti <repo>, validating the target repo fir...(AI_HYDRA_LEO_CPT_TI_IT)
119-119: The use of the topicnodejsmatches GitHub topic naming; no change required.🧰 Tools
🪛 LanguageTool
[uncategorized] ~119-~119: The official spelling of this programming framework is “Node.js”.
Context: ...f-nodejs-pr-testing.yml| Repos withnodejstopic | |replicate_nodejs_releas...(NODE_JS)
110-124: Global replicator details are clear
Job names, file sync targets, and descriptions are presented clearly.🧰 Tools
🪛 LanguageTool
[uncategorized] ~119-~119: The official spelling of this programming framework is “Node.js”.
Context: ...f-nodejs-pr-testing.yml| Repos withnodejstopic | |replicate_nodejs_releas...(NODE_JS)
126-137: Opt-in/out instructions are well-defined
Steps for opting in and out of global workflows are clear and actionable.🧰 Tools
🪛 LanguageTool
[style] ~132-~132: Consider a more expressive alternative.
Context: ...to trigger it manually for you. To do this, reach out on Slack or open an iss...(DO_ACHIEVE)
138-147: Semantic release guidance is accurate
The explanation of Semantic Release and Conventional Commits is correct and detailed.
148-157: Slash commands section is useful
Describes the purpose and usage of slash commands effectively.🧰 Tools
🪛 LanguageTool
[uncategorized] ~150-~150: The preposition ‘to’ seems more likely in this position.
Context: ...shared workflows, repositories that opt in automatically get support for issue and...(AI_HYDRA_LEO_REPLACE_IN_TO)
158-168: Setup requirements are complete
Necessary steps for enabling global workflows are clearly outlined.
|
@derberg @bandantonio your help here |
| weight: 120 | ||
| --- | ||
|
|
||
| This document outlines how AsyncAPI utilizes GitHub Actions to automate and optimize workflows. It provides a comprehensive guide for maintainers and contributors, explaining global and local workflows, common commands, repository setup, and best practices. |
| - [Slash commands](#slash-commands) | ||
| - [Basic requirements to use global workflows](#basic-requirements-to-use-global-workflows) | ||
|
|
||
| ## TL;DR |
| [GitHub Actions](https://docs.github.com/actions) is a continuous integration and continuous delivery (CI/CD) platform that automates software development workflows directly within a GitHub repository. | ||
|
|
||
| At AsyncAPI, GitHub Actions is crucial for maintaining consistency, efficiency, and quality across our projects by handling repetitive tasks automatically. |
There was a problem hiding this comment.
Third duplication. Basically the same concepts are described again in slightly different words.
I would suggest combining all the introductory information into the "Introduction" or "Overview" section after the Table of Contents. A short intro before TOC looks strange
|
|
||
| ## Table of Contents | ||
| - [Table of Contents](#table-of-contents) | ||
| - [TL;DR](#tldr) |
There was a problem hiding this comment.
Never use such wording in guides for newcomers
There was a problem hiding this comment.
What's the word? TL;DR?
There was a problem hiding this comment.
Yup.
Better use "Introduction", or "Overview"
| - [Types of GitHub Actions workflows](#types-of-github-actions-workflows) | ||
| - [Local workflows](#local-workflows) | ||
| - [Global workflows](#global-workflows) | ||
| - [Global workflows overview](#global-workflows-overview) |
There was a problem hiding this comment.
Why is this a separate section? Can it be merged with the previous section on line 14?
| - [Local workflows](#local-workflows) | ||
| - [Global workflows](#global-workflows) | ||
| - [Global workflows overview](#global-workflows-overview) | ||
| - [Global replicator workflow](#global-replicator-workflow) |
There was a problem hiding this comment.
- Question 1: Same here. Can this section be a child of the Global workflows ?
- Question 2: Why did you choose this particular (and not any other from the list below) workflow to describe in detail? What's so special about it?
There was a problem hiding this comment.
Because the Global replicator workflow is an action responsible for distributing other workflows in whatever repository we want. So it's important to go over all the jobs under this workflow.
Also, most of the structure of this document was decided a while ago by the community based on this thread
|
|
||
| The table below provides an overview of all the global workflows available in the AsyncAPI organization: | ||
|
|
||
| | Workflow Name | Description | |
There was a problem hiding this comment.
What would be the process of maintaining this table up-to-date once any workflow gets changed?
There was a problem hiding this comment.
same question from my side
it is already not very accurate, as there is no workflow names "PTAL command" but "Please take a Look" (https://github.com/asyncapi/.github/blob/master/.github/workflows/please-take-a-look-command.yml)
imho better in overview explain how to learn about each workflow, on an example
and for good docs, rather put comments inside YAML files - the advantage is that if there is a good docs in yaml, it will be easier to maintain, and also anyone seeing a copy of such workflow in their repo - they can easily learn what it does directly from the YAML file copy
Co-authored-by: Antonio <[email protected]>
Co-authored-by: Antonio <[email protected]>
Co-authored-by: Antonio <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
docs/onboarding-guide/github-actions.md (2)
6-7: Consider relocating the introductory paragraph. A brief description before the TOC can feel unexpected; you might move or merge this content into the "Introduction to GitHub Actions" section for better flow.
11-14: Avoid duplicate entries in the Table of Contents. The "Global workflows" item appears both under "Types of GitHub Actions workflows" and as a standalone "Global workflows overview"; consider renaming or consolidating these entries to reduce confusion.🧰 Tools
🪛 LanguageTool
[grammar] ~12-~12: This phrase is duplicated. You should probably use “workflows Global” only once.
Context: ...of-github-actions-workflows) - Local workflows - Global workflows - [Global workflows overview](#global-workflows-o...(PHRASE_REPETITION)
🧹 Nitpick comments (4)
docs/onboarding-guide/github-actions.md (4)
87-87: Add missing verb in Docker description. The phrase "only if aDockerfilepresent" should read "only if aDockerfileis present" to improve readability.- only if a `Dockerfile` present in the repository root + only if a `Dockerfile` is present in the repository root
93-94: Use plural verb for consistency. Change “is mentioned” to “are mentioned” since it refers to multiple mentions (issues, PRs, discussions).- whenever `@asyncapi/tsc_members` is mentioned in issues, PRs, discussions, or their comments + whenever `@asyncapi/tsc_members` are mentioned in issues, PRs, discussions, or their comments🧰 Tools
🪛 LanguageTool
[uncategorized] ~94-~94: The verb “is” doesn’t seem to fit in this context, “are” is probably more formally correct.
Context: ... email whenever@asyncapi/tsc_membersis mentioned in issues, PRs, discussions, ...(AI_HYDRA_LEO_CPT_IS_ARE)
127-129: Refine wording for clarity. Instead of “To do this,” consider a more descriptive phrase such as “To opt in manually,” which directly reflects the action being taken.- To do this, reach out on Slack or open an issue, and a maintainer can run the “Global workflow to rule them all” action, optionally targeting your repo by name. + To opt in manually, reach out on Slack or open an issue, and a maintainer can run the “Global workflow to rule them all” action, optionally targeting your repository by name.🧰 Tools
🪛 LanguageTool
[style] ~129-~129: Consider a more expressive alternative.
Context: ...to trigger it manually for you. To do this, reach out on Slack or open an iss...(DO_ACHIEVE)
147-151: Improve preposition usage. Consider rephrasing “repositories that opt in automatically get support for issue and pull request commands” to “repositories that opt in get automatic support for issue and pull request commands” for smoother flow.🧰 Tools
🪛 LanguageTool
[uncategorized] ~147-~147: The preposition ‘to’ seems more likely in this position.
Context: ...shared workflows, repositories that opt in automatically get support for issue and...(AI_HYDRA_LEO_REPLACE_IN_TO)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/github-actions.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/onboarding-guide/github-actions.md
[grammar] ~12-~12: This phrase is duplicated. You should probably use “workflows Global” only once.
Context: ...of-github-actions-workflows) - Local workflows - Global workflows - [Global workflows overview](#global-workflows-o...
(PHRASE_REPETITION)
[grammar] ~88-~88: It seems that a pronoun is missing.
Context: ...present** in the repository root. | | If Go PR testing | Runs on pull request ...
(IF_VB)
[grammar] ~88-~88: Possible typo detected.
Context: ...f the project contains a go.mod file, it lints and tests the Go code across Linu...
(PRP_VB)
[uncategorized] ~94-~94: The verb “is” doesn’t seem to fit in this context, “are” is probably more formally correct.
Context: ... email whenever @asyncapi/tsc_members is mentioned in issues, PRs, discussions, ...
(AI_HYDRA_LEO_CPT_IS_ARE)
[uncategorized] ~98-~98: “ti” (solization) seems less likely than “it
Context: ... commenting /transfer-issue <repo> or /ti <repo>, validating the target repo fir...
(AI_HYDRA_LEO_CPT_TI_IT)
[uncategorized] ~116-~116: The official spelling of this programming framework is “Node.js”.
Context: ...f-nodejs-pr-testing.yml | Repos withnodejstopic | |replicate_nodejs_releas...
(NODE_JS)
[style] ~129-~129: Consider a more expressive alternative.
Context: ...to trigger it manually for you. To do this, reach out on Slack or open an iss...
(DO_ACHIEVE)
[uncategorized] ~147-~147: The preposition ‘to’ seems more likely in this position.
Context: ...shared workflows, repositories that opt in automatically get support for issue and...
(AI_HYDRA_LEO_REPLACE_IN_TO)
🔇 Additional comments (6)
docs/onboarding-guide/github-actions.md (6)
1-4: Front matter looks good. The YAML header is correctly structured and follows the existing documentation conventions.
21-29: Clear and concise TL;DR. The bullet points effectively summarize the guide's key points and are easy to scan.
30-35: Solid introduction to GitHub Actions. This section clearly sets the context and purpose for readers new to the platform.
36-54: Well-structured explanation of workflow types. The distinction between local and global workflows is clearly articulated.
135-144: Clear explanation of semantic release. This section effectively communicates how Conventional Commits drive the automation of package releases.
155-164: Well-defined setup steps. The prerequisites for enabling global workflows are clearly outlined and actionable.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (4)
docs/onboarding-guide/github-actions.md (4)
2-2: Nitpick: use consistent frontmatter quoting
Other Markdown files in this repository generally use double quotes for frontmatter values. Consider changing:-title: 'Utilizing GitHub Actions' +title: "Utilizing GitHub Actions"
64-95: Improve readability of the global workflows table
The table of all global workflows is very long and may overwhelm readers. You could:
- Split it into logical categories (e.g., Automations, Maintenance, Notifications).
- Use collapsible
<details>blocks for less-frequently used workflows.- Link to the
.githubrepo for full details and only list the top ~10 most commonly used workflows here.🧰 Tools
🪛 LanguageTool
[grammar] ~79-~79: It seems that a pronoun is missing.
Context: ...present** in the repository root. | | If Go PR testing | Runs on pull request ...(IF_VB)
[grammar] ~79-~79: Possible typo detected.
Context: ...f the project contains ago.modfile, it lints and tests the Go code across Linu...(PRP_VB)
79-80: Optional refinement: simplify phrasing for Go PR testing
For consistency and brevity, you might rephrase:- if the project contains a `go.mod` file … + if a `go.mod` file is present …🧰 Tools
🪛 LanguageTool
[grammar] ~79-~79: It seems that a pronoun is missing.
Context: ...present** in the repository root. | | If Go PR testing | Runs on pull request ...(IF_VB)
[grammar] ~79-~79: Possible typo detected.
Context: ...f the project contains ago.modfile, it lints and tests the Go code across Linu...(PRP_VB)
119-121: Nitpick: refine phrasing for opt-in instructions
Instead of “To do this, reach out…”, you could write:To opt in, reach out on Slack or open an issue so that a maintainer can run the “Global Workflow to Rule Them All” action.
This ties the instruction directly to the “Opt-in” heading.
🧰 Tools
🪛 LanguageTool
[style] ~120-~120: Consider a more expressive alternative.
Context: ...to trigger it manually for you. To do this, reach out on Slack or open an iss...(DO_ACHIEVE)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/github-actions.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/onboarding-guide/github-actions.md
[grammar] ~8-~8: This phrase is duplicated. You should probably use “workflows Global” only once.
Context: ...of-github-actions-workflows) - Local workflows - Global workflows - [Global workflows overview](#global-workflows-o...
(PHRASE_REPETITION)
[grammar] ~79-~79: It seems that a pronoun is missing.
Context: ...present** in the repository root. | | If Go PR testing | Runs on pull request ...
(IF_VB)
[grammar] ~79-~79: Possible typo detected.
Context: ...f the project contains a go.mod file, it lints and tests the Go code across Linu...
(PRP_VB)
[uncategorized] ~107-~107: The official spelling of this programming framework is “Node.js”.
Context: ...f-nodejs-pr-testing.yml | Repos withnodejstopic | |replicate_nodejs_releas...
(NODE_JS)
[style] ~120-~120: Consider a more expressive alternative.
Context: ...to trigger it manually for you. To do this, reach out on Slack or open an iss...
(DO_ACHIEVE)
🔇 Additional comments (1)
docs/onboarding-guide/github-actions.md (1)
78-79:⚠️ Potential issueCorrect missing verb in Docker PR testing row
The phrase "only if aDockerfilepresent" is missing the verb “is.” Apply this patch:- tests whether a Docker image can be built from the project **only if a `Dockerfile` present** in the repository root. + tests whether a Docker image can be built from the project **only if a `Dockerfile` is present** in the repository root.Likely an incorrect or invalid review comment.
🧰 Tools
🪛 LanguageTool
[grammar] ~79-~79: It seems that a pronoun is missing.
Context: ...present** in the repository root. | | If Go PR testing | Runs on pull request ...(IF_VB)
[grammar] ~79-~79: Possible typo detected.
Context: ...f the project contains ago.modfile, it lints and tests the Go code across Linu...(PRP_VB)
|
Hello @bandantonio I've fixed the duplicates you talked about above. As for the TOC, most of the items I wanted to take out couldn't go because it's generated automatically based on the headings in the document. Also, as per your comments about the structure, I added a link to the thread about the discussion of this document. |
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/onboarding-guide/github-actions.md (1)
6-18: 🛠️ Refactor suggestionImprove the Table of Contents structure.
- Add a clear “## Table of Contents” heading above this list for better discoverability.
- Nest “Local workflows” and “Global workflows” under the “Types of GitHub Actions workflows” entry instead of as top-level items.
- Remove or merge the separate “Global workflows overview” entry under the “Global workflows” section to eliminate redundancy.
@@ -5,13 +5,16 @@ - [Overview](#overview) +- ## Table of Contents +- - [Types of GitHub Actions workflows](#types-of-github-actions-workflows) - - [Local workflows](#local-workflows) - - [Global workflows](#global-workflows) - [Global workflows overview](#global-workflows-overview) + - [Local workflows](#local-workflows) + - [Global workflows](#global-workflows) + - [Global workflows overview](#global-workflows-overview) - [Global replicator workflow](#global-replicator-workflow) - [How to opt in or out of global workflows](#how-to-opt-in-or-out-of-global-workflows) - [Opt-in](#opt-in)🧰 Tools
🪛 LanguageTool
[grammar] ~8-~8: This phrase is duplicated. You should probably use “workflows Global” only once.
Context: ...of-github-actions-workflows) - Local workflows - Global workflows - [Global workflows overview](#global-workflows-o...(PHRASE_REPETITION)
🧹 Nitpick comments (1)
docs/onboarding-guide/github-actions.md (1)
66-69: Fix missing space in workflow name. Improve readability by adding a space before the parenthesis.-| **Automerge for Humans(Add Ready to Merge or Do Not Merge)** | Enables merging PRs via slash commands such as `/rtm`, `/dnm`, `/au`... +| **Automerge for Humans (Add Ready to Merge or Do Not Merge)** | Enables merging PRs via slash commands such as `/rtm`, `/dnm`, `/au`...
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/github-actions.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/onboarding-guide/github-actions.md
[grammar] ~8-~8: This phrase is duplicated. You should probably use “workflows Global” only once.
Context: ...of-github-actions-workflows) - Local workflows - Global workflows - [Global workflows overview](#global-workflows-o...
(PHRASE_REPETITION)
[grammar] ~79-~79: It seems that a pronoun is missing.
Context: ...present** in the repository root. | | If Go PR testing | Runs on pull request ...
(IF_VB)
[grammar] ~79-~79: Possible typo detected.
Context: ...f the project contains a go.mod file, it lints and tests the Go code across Linu...
(PRP_VB)
[uncategorized] ~85-~85: The verb “is” doesn’t seem to fit in this context, “are” is probably more formally correct.
Context: ... email whenever @asyncapi/tsc_members is mentioned in issues, PRs, discussions, ...
(AI_HYDRA_LEO_CPT_IS_ARE)
[uncategorized] ~89-~89: “ti” (solization) seems less likely than “it
Context: ... commenting /transfer-issue <repo> or /ti <repo>, validating the target repo fir...
(AI_HYDRA_LEO_CPT_TI_IT)
[uncategorized] ~107-~107: The official spelling of this programming framework is “Node.js”.
Context: ...f-nodejs-pr-testing.yml | Repos withnodejstopic | |replicate_nodejs_releas...
(NODE_JS)
[style] ~120-~120: Consider a more expressive alternative.
Context: ...to trigger it manually for you. To do this, reach out on Slack or open an iss...
(DO_ACHIEVE)
[uncategorized] ~138-~138: The preposition ‘to’ seems more likely in this position.
Context: ...shared workflows, repositories that opt in automatically get support for issue and...
(AI_HYDRA_LEO_REPLACE_IN_TO)
🔇 Additional comments (11)
docs/onboarding-guide/github-actions.md (11)
1-4: Front matter is valid. YAML metadata is correctly formatted and will be parsed by the site generator without issues.
19-26: Overview section looks great. It concisely introduces GitHub Actions and explains the purpose of this guide within the AsyncAPI ecosystem.
27-29: Types of workflows section is clear. The distinction between local and global workflows is well-defined.
31-45: Local workflows section is comprehensive. It covers common CI/CD tasks and key points for maintainers without overloading the reader.
48-57: Global workflows introduction is effective. It clearly communicates the benefits and maintenance model of shared workflows.
60-63: Global workflows overview header is appropriate. It sets the stage for the detailed table that follows.
98-105: Global replicator workflow section is thorough. The job table clearly defines each task, the files it syncs, and target repositories.
114-125: Opt-in/Opt-out instructions are concise. Provides clear, actionable steps for maintainers to toggle global workflows.🧰 Tools
🪛 LanguageTool
[style] ~120-~120: Consider a more expressive alternative.
Context: ...to trigger it manually for you. To do this, reach out on Slack or open an iss...(DO_ACHIEVE)
126-135: Semantic release section is accurate. Correctly outlines Conventional Commits and the automation flow for Node.js projects.
136-144: Slash commands section is effective. Highlights the/helpcommand and provides a clear example for contributors.🧰 Tools
🪛 LanguageTool
[uncategorized] ~138-~138: The preposition ‘to’ seems more likely in this position.
Context: ...shared workflows, repositories that opt in automatically get support for issue and...(AI_HYDRA_LEO_REPLACE_IN_TO)
145-155: Basic requirements section is practical. Lists necessary setup steps in a logical order to ensure smooth onboarding.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/onboarding-guide/github-actions.md (1)
10-14: Consolidate duplicate TOC entries for Global workflows
There’s both a “Global workflows” entry and a nested “Global workflows overview” entry under it, echoing previous feedback. Merging or removing the nested overview link will streamline navigation and eliminate duplication.🧰 Tools
🪛 LanguageTool
[grammar] ~11-~11: This phrase is duplicated. You should probably use “workflows Global” only once.
Context: ...of-github-actions-workflows) - Local workflows - Global workflows - [Global workflows overview](#global-workflows-o...(PHRASE_REPETITION)
🧹 Nitpick comments (4)
docs/onboarding-guide/github-actions.md (4)
8-8: Remove redundant self-link in TOC
The TOC lists “Table of Contents” immediately below its own heading, which is unnecessary. Removing this entry will reduce noise and avoid confusing readers.
65-96: Improve readability of the global workflows list
This large table may overwhelm new contributors. Consider splitting it into smaller, categorized tables, moving it to a dedicated reference page, or wrapping it in a collapsible<details>block so the core guide stays focused.🧰 Tools
🪛 LanguageTool
[grammar] ~80-~80: It seems that a pronoun is missing.
Context: ...present** in the repository root. | | If Go PR testing | Runs on pull request ...(IF_VB)
[grammar] ~80-~80: Possible typo detected.
Context: ...f the project contains ago.modfile, it lints and tests the Go code across Linu...(PRP_VB)
139-139: Use consistent heading capitalization
Section headings use Title Case elsewhere (e.g., “Local workflows”), but “## Semantic release and automation” is in sentence case. For consistency, rename to “## Semantic Release and Automation”.
149-157: Expand slash commands section for quick reference
Right now only/helpand/rtmare called out. It would help contributors to see all commonly used slash commands (e.g.,/gfi,/dnm,/bounty,/transfer-issue) or link to a full list so they don’t have to search elsewhere.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/github-actions.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/onboarding-guide/github-actions.md
[grammar] ~11-~11: This phrase is duplicated. You should probably use “workflows Global” only once.
Context: ...of-github-actions-workflows) - Local workflows - Global workflows - [Global workflows overview](#global-workflows-o...
(PHRASE_REPETITION)
[grammar] ~80-~80: It seems that a pronoun is missing.
Context: ...present** in the repository root. | | If Go PR testing | Runs on pull request ...
(IF_VB)
[grammar] ~80-~80: Possible typo detected.
Context: ...f the project contains a go.mod file, it lints and tests the Go code across Linu...
(PRP_VB)
[style] ~118-~118: Consider a more expressive alternative.
Context: ...r to trigger it manually for you. To do this, reach out on Slack or open an iss...
(DO_ACHIEVE)
[uncategorized] ~133-~133: The official spelling of this programming framework is “Node.js”.
Context: ...f-nodejs-pr-testing.yml | Repos withnodejstopic | |replicate_nodejs_releas...
(NODE_JS)
There was a problem hiding this comment.
@Aahil13 lgtm, the last update brings more structure and consistency, thank you.
|
@derberg I need your review to make sure we got everything correct |
|
|
||
| The basic requirements are: | ||
|
|
||
| - **Add the bots team as maintainers**: In the repository settings, under *Collaborators and Teams*, add the bots team with maintainer permissions. |
There was a problem hiding this comment.
provide team name
@asyncapi/bots
| The basic requirements are: | ||
|
|
||
| - **Add the bots team as maintainers**: In the repository settings, under *Collaborators and Teams*, add the bots team with maintainer permissions. | ||
| - **Add Eve to code owners**: Ensure that the Eve bot account is listed as a code owner to allow automatic approval of bot-generated pull requests. |
There was a problem hiding this comment.
provide the name so people knwo what to put in CODEOWNERS file
@asyncapi-bot-eve
and yeah, explain that code owner means someone in CODEOWNER
| | `replicate_docker_workflows` | Pushes Docker PR testing workflows | `.github/workflows/if-docker-pr-testing.yml` | Repos with `docker` topic | | ||
| | `replicate_validate_workflow_schema`| Adds YAML validation workflows | `.github/workflows/validate-workflow-schema.yml`| Repos with validation topic | | ||
|
|
||
| ## Semantic release and automation |
There was a problem hiding this comment.
should this be here? especially that semantic release is no longer the only standard here, we also use changeset in some monorepos
|
|
||
| ## Global replicator workflow | ||
|
|
||
| The [Global Replicator Workflow](https://github.com/asyncapi/.github/blob/master/.github/workflows/global-replicator.yml) keeps key files in sync across AsyncAPI repositories. |
There was a problem hiding this comment.
I'm not so sure it is good idea to have this table.
even now it is not up to date with what is in https://github.com/asyncapi/.github/blob/master/.github/workflows/global-replicator.yml file - long term it might event get worse
wouldn't it be better to make sure https://github.com/asyncapi/.github/blob/master/.github/workflows/global-replicator.yml has proper comments and descriptions inside YAML, and here in docs, it is explaned that there are different jobs, and how and where to find more details?
|
|
||
| The table below provides an overview of all the global workflows available in the AsyncAPI organization: | ||
|
|
||
| | Workflow Name | Description | |
There was a problem hiding this comment.
same question from my side
it is already not very accurate, as there is no workflow names "PTAL command" but "Please take a Look" (https://github.com/asyncapi/.github/blob/master/.github/workflows/please-take-a-look-command.yml)
imho better in overview explain how to learn about each workflow, on an example
and for good docs, rather put comments inside YAML files - the advantage is that if there is a good docs in yaml, it will be easier to maintain, and also anyone seeing a copy of such workflow in their repo - they can easily learn what it does directly from the YAML file copy
Related issue(s): See also #1622
Summary by CodeRabbit