diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 000000000..4a3620353 --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,60 @@ +## JSON Schema Website CI/CD Workflow Guidelines + +### Overview + +This document outlines the guidelines for contributing to and maintaining GitHub Actions workflows in the JSON Schema Website project. Adherence to these guidelines ensures consistency, efficiency, and ease of maintenance across our CI/CD processes. + +### General Principles + +- **Change Management**: Modifications to files in this directory are closely monitored. Changes will trigger unauthorized file changes workflow during pull request checks. Only make changes when explicitly advised by a project contributor or maintainer. +- **Documentation and Naming**: Use descriptive, self-explanatory names for workflows, jobs, and steps. Include clear comments within workflow files to explain complex configurations. + +### YAML Workflow File Structure + +Our YAML files are organized based on specific roles and event triggers. When creating or modifying workflows, ensure that: +- The file roles described below are strictly maintained. +- Job sequences within workflows are preserved using [GitHub Action job dependencies](https://docs.github.com/en/actions/using-workflows/using-jobs-in-a-workflow#defining-prerequisite-jobs). + +### File Categorization + +Organize workflow files based on their primary event trigger: + +- **Issue Workflows**: + - [Issue Workflow](./issue.yml): Handles issue-related events such as opening, closing, or labeling issues. + +- **Pull Request Workflows**: + - [CI Workflow](./ci.yml): Runs for all contributors on pull requests, performing code-quality checks, unauthorized file changes detection, and build processes. + - [PR Interaction Workflow](./pull-request-target.yml): Contains workflows specifically for first-time contributors, such as welcome messages. + +### Exceptions to File Categorization + +Separate files may be created for workflows that: + +- Require unique `cron` schedules for periodic execution. + Examples: + - [Link Checker](./link-checker.yml): Periodically checks for broken links in the repository. + - [Mark stale issues and pull requests](./stale-issues-prs.yml): Automatically labels and closes stale issues and PRs. + - [Dependabot](../dependabot.yml): Keeps dependencies up-to-date. + +- Need specific `paths` triggers, activating only when files in particular directories are modified. + Example: + - [New Implementation Commenter](./new-implementation.yml): Adds comments when new implementation files are added. + +- Only work correctly if they have a dedicated file. + Examples: + - [Preview Deployment](./preview-deployment.yml): Deploys preview environments for pull requests. + - [Production Deployment](./production-deployment.yml): Handles production deployments. + - [CodeQL Code Scanning](./codeql.yml): Performs code security analysis. + - [Check PR Dependencies](./pr-dependencies.yml): Enforces dependencies between PRs based on opening comments. + +### Workflow Maintenance + +To ensure the efficiency and reliability of our workflows, follow these maintenance guidelines: + +- **Regular Review**: Review and update workflows at least quarterly to incorporate new features or best practices. +- **Dependency Updates**: Keep workflow dependencies up-to-date by reviewing and applying Dependabot suggestions promptly. +- **Documentation**: Update workflow documentation immediately after any changes or modifications to keep it current. +- **Performance Monitoring**: Regularly check workflow run times and optimize where possible to reduce GitHub Actions usage. +- **Security Checks**: Ensure that workflows using secrets or accessing sensitive data are properly secured and follow least privilege principles. + +These guidelines aim to maintain the integrity and efficiency of our CI/CD processes. Always consult with the team before making significant changes to any workflow. \ No newline at end of file diff --git a/.github/workflows/pull-request.yml b/.github/workflows/ci.yml similarity index 94% rename from .github/workflows/pull-request.yml rename to .github/workflows/ci.yml index 7528a0ce0..f4bab9cad 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/ci.yml @@ -1,11 +1,11 @@ -name: PR Workflow +name: CI on: pull_request: types: [opened, reopened, synchronize] jobs: - linting_and_type-checking: - name: Linting, Formatting and Type checking + code-quality-checks: + name: Code Quality Checks runs-on: ubuntu-latest steps: - name: Checkout repository @@ -44,8 +44,8 @@ jobs: - name: Type checking run: yarn run typecheck - Check-Unauthorized-File-Changes: - name: Checks if no unauthorized files are changed + check-unauthorized-file-changes: + name: Check Unauthorized File Changes if: ${{github.actor != 'dependabot[bot]'}} runs-on: ubuntu-latest steps: @@ -94,8 +94,8 @@ jobs: build: name: Build check + needs: code-quality-checks runs-on: ubuntu-latest - needs: linting_and_type-checking steps: - name: Checkout repository uses: actions/checkout@v4 diff --git a/.github/workflows/issue.yml b/.github/workflows/issue.yml index b228fd687..dfaf9815f 100644 --- a/.github/workflows/issue.yml +++ b/.github/workflows/issue.yml @@ -5,25 +5,25 @@ on: types: ['opened'] jobs: - Issue-Labeler: - name: Adding Label to issue - runs-on: ubuntu-latest - steps: - - uses: Renato66/auto-label@v3.0.0 - with: - repo-token: ${{ secrets.GITHUB_TOKEN }} - ignore-comments: true - default-labels: '["Status: Triage"]' + issue-labeler: + name: Adding Label to Issue + runs-on: ubuntu-latest + steps: + - name: Auto Label Issue + uses: Renato66/auto-label@v3.0.0 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + ignore-comments: true + default-labels: '["Status: Triage"]' - Issue-Greeting: - name: Greeting Message to User - runs-on: ubuntu-latest - steps: - - name: Greeting Message to User - uses: actions/first-interaction@v1 - with: - repo-token: ${{ secrets.GITHUB_TOKEN }} - issue-message: | - Welcome to the [JSON Schema](https://json-schema.org/) Community. We are so excited you are here! Thanks a lot for reporting your first issue!! 🎉🎉 Please make sure to take a look to our [contributors guide](https://github.com/json-schema-org/website/blob/main/CONTRIBUTING.md) if you plan on opening a pull request. - For more details check out [README.md](https://github.com/json-schema-org/website?tab=readme-ov-file#-welcome-to-the-json-schema-website) file. - \ No newline at end of file + issue-greeting: + name: Greeting Message to User + runs-on: ubuntu-latest + steps: + - name: Send Greeting Message + uses: actions/first-interaction@v1 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + issue-message: | + Welcome to the [JSON Schema](https://json-schema.org/) Community. We are so excited you are here! Thanks a lot for reporting your first issue!! 🎉🎉 Please make sure to take a look at our [contributors guide](https://github.com/json-schema-org/website/blob/main/CONTRIBUTING.md) if you plan on opening a pull request. + For more details, check out the [README.md](https://github.com/json-schema-org/website?tab=readme-ov-file#-welcome-to-the-json-schema-website) file. diff --git a/.github/workflows/links.yml b/.github/workflows/link-checker.yml similarity index 98% rename from .github/workflows/links.yml rename to .github/workflows/link-checker.yml index 6e32ce6da..73c57b9d3 100644 --- a/.github/workflows/links.yml +++ b/.github/workflows/link-checker.yml @@ -8,6 +8,7 @@ on: jobs: linkChecker: + name: Check and Report Broken Links runs-on: ubuntu-latest steps: - name: Checkout Repository diff --git a/.github/workflows/pull-request-target.yml b/.github/workflows/pull-request-target.yml index d54a71298..e663c1337 100644 --- a/.github/workflows/pull-request-target.yml +++ b/.github/workflows/pull-request-target.yml @@ -1,4 +1,4 @@ -name: Pull Request Target Workflow +name: PR Interaction Workflow on: pull_request_target: diff --git a/.github/workflows/stale.yml b/.github/workflows/stale-issues-prs.yml similarity index 100% rename from .github/workflows/stale.yml rename to .github/workflows/stale-issues-prs.yml