diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 00000000000..94bceb23e12 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,19 @@ +{ + "name": "Jekyll website", + "image": "mcr.microsoft.com/devcontainers/jekyll:latest", + "features": { + "ghcr.io/devcontainers/features/node:1": { + "version": "22" + }, + "ghcr.io/devcontainers/features/ruby:1": { + "version": "3.3.5" + } + }, + "forwardPorts": [ + // Jekyll server + 4000, + // Live reload server + 35729 + ], + "postCreateCommand": "bundle exec jekyll serve --incremental" +} diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 8dc181fec96..4655c5304be 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -4,16 +4,41 @@ updates: directory: "/" schedule: interval: daily - time: "10:00" - timezone: Europe/Vienna - pull-request-branch-name: - separator: "-" open-pull-requests-limit: 99 rebase-strategy: disabled + commit-message: + prefix: "chore(deps)" + groups: + dependencies: + applies-to: version-updates + update-types: + - "minor" + - "patch" - package-ecosystem: "github-actions" directory: "/" schedule: interval: daily open-pull-requests-limit: 99 rebase-strategy: disabled - + commit-message: + prefix: "chore(deps)" + groups: + dependencies: + applies-to: version-updates + update-types: + - "minor" + - "patch" + - package-ecosystem: bundler + directory: "/" + schedule: + interval: daily + versioning-strategy: increase + open-pull-requests-limit: 99 + commit-message: + prefix: "chore(deps)" + groups: + dependencies: + applies-to: version-updates + update-types: + - "minor" + - "patch" diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 00000000000..26e72eb6328 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,77 @@ +# For most projects, this workflow file will not need changing; you simply need +# to commit it to your repository. +# +# You may wish to alter this file to override the set of languages analyzed, +# or to provide custom queries or build logic. +# +# ******** NOTE ******** +# We have attempted to detect the languages in your repository. Please check +# the `language` matrix defined below to confirm you have the correct set of +# supported CodeQL languages. +# +name: "CodeQL Advanced" + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + schedule: + - cron: '35 9 * * 0' + +jobs: + analyze: + name: Analyze (${{ matrix.language }}) + # Runner size impacts CodeQL analysis time. To learn more, please see: + # - https://gh.io/recommended-hardware-resources-for-running-codeql + # - https://gh.io/supported-runners-and-hardware-resources + # - https://gh.io/using-larger-runners (GitHub.com only) + # Consider using larger runners or machines with greater resources for possible analysis time improvements. + runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }} + permissions: + # required for all workflows + security-events: write + + # required to fetch internal or private CodeQL packs + packages: read + + # only required for workflows in private repositories + actions: read + contents: read + + strategy: + fail-fast: false + matrix: + include: + - language: actions + build-mode: none + - language: javascript-typescript + build-mode: none + - language: ruby + build-mode: none + + steps: + - name: Checkout repository + uses: actions/checkout@v7 + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v4 + with: + languages: ${{ matrix.language }} + build-mode: ${{ matrix.build-mode }} + + - name: Run manual build steps + if: matrix.build-mode == 'manual' + shell: bash + run: | + echo 'If you are using a "manual" build mode for one or more of the' \ + 'languages you are analyzing, replace this with the commands to build' \ + 'your code, for example:' + echo ' make bootstrap' + echo ' make release' + exit 1 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v4 + with: + category: "/language:${{matrix.language}}" diff --git a/.github/workflows/jekyll.yml b/.github/workflows/jekyll.yml new file mode 100644 index 00000000000..d967f354ac4 --- /dev/null +++ b/.github/workflows/jekyll.yml @@ -0,0 +1,51 @@ +# This workflow uses actions that are not certified by GitHub. +# They are provided by a third-party and are governed by +# separate terms of service, privacy policy, and support +# documentation. + +# Sample workflow for building and deploying a Jekyll site to GitHub Pages +name: Deploy Jekyll site to Pages +on: + # Runs on pushes targeting the default branch + push: + branches: ["main"] + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v7 + - name: Setup Pages + uses: actions/configure-pages@v6.0.0 + - name: Build with Jekyll + uses: actions/jekyll-build-pages@44a6e6beabd48582f863aeeb6cb2151cc1716697 # v1 + with: + source: ./ + destination: ./_site + - name: Upload artifact + # Automatically uploads an artifact from the './_site' directory by default + uses: actions/upload-pages-artifact@v5.0.0 + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v5.0.0 diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml new file mode 100644 index 00000000000..2020e81b74b --- /dev/null +++ b/.github/workflows/link-check.yml @@ -0,0 +1,30 @@ +name: Weekly External Link Check +on: + schedule: + # Every Monday at 08:00 UTC + - cron: "0 8 * * 1" + workflow_dispatch: +permissions: + contents: read +jobs: + link-check: + runs-on: ubuntu-latest + steps: + - name: Set up Git repository + uses: actions/checkout@v7 + - name: Set up Ruby + uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1 + with: + bundler-cache: true + - name: Set up Node + uses: actions/setup-node@v7.0.0 + - name: Bootstrap + run: script/bootstrap + env: + SKIP_BUNDLER: true + - name: Build site + run: script/build --config _config.yml,test/_config.yml + - name: Check links (including external URLs) + run: script/html-proofer + env: + CHECK_EXTERNAL_LINKS: true diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index 8163ee6e226..a4c6e017f18 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -2,21 +2,23 @@ name: Mark stale PRs on: workflow_dispatch: schedule: - - cron: "0 12 * * *" - + - cron: "0 12 * * *" +permissions: + contents: read + issues: write + pull-requests: write jobs: stale: runs-on: ubuntu-latest steps: - - uses: actions/stale@v8 - with: - stale-pr-message: > - This pull request has been automatically marked as stale because it has not - had recent activity. It will be closed if no further activity occurs. - Thank you for your contributions. - stale-pr-label: "stale" - exempt-pr-labels: "pinned,security" - days-before-pr-stale: 30 - days-before-pr-close: 7 - ascending: true - operations-per-run: 100 + - uses: actions/stale@v11.0.0 + with: + stale-pr-message: > + This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions. + + stale-pr-label: "stale" + exempt-pr-labels: "pinned,security" + days-before-pr-stale: 30 + days-before-pr-close: 7 + ascending: true + operations-per-run: 100 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index d1e7bd1955e..622f41b989a 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -1,28 +1,26 @@ name: GitHub Actions CI on: push: - branches: master - pull_request: [] + branches: main + pull_request: merge_group: +permissions: + contents: read jobs: tests: runs-on: ubuntu-latest steps: - - name: Set up Git repository - uses: actions/checkout@v3 - - - name: Set up Ruby - uses: ruby/setup-ruby@v1 - with: - bundler-cache: true - - - name: Set up Node - uses: actions/setup-node@v3 - - - name: Bootstrap - run: script/bootstrap - env: - SKIP_BUNDLER: true - - - name: Tests - run: script/test + - name: Set up Git repository + uses: actions/checkout@v7 + - name: Set up Ruby + uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1 + with: + bundler-cache: true + - name: Set up Node + uses: actions/setup-node@v7.0.0 + - name: Bootstrap + run: script/bootstrap + env: + SKIP_BUNDLER: true + - name: Tests + run: script/test diff --git a/.gitignore b/.gitignore index 177fab1a1b5..1442c5e5731 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ .bundle .jekyll-metadata .ruby-version +.tool-versions .sass-cache/ /vendor _site/ @@ -10,4 +11,3 @@ bin css/main.scss test/node_modules test/package-lock.json -Gemfile.lock diff --git a/.ruby-version b/.ruby-version index a603bb50a29..fa7adc7ac72 100644 --- a/.ruby-version +++ b/.ruby-version @@ -1 +1 @@ -2.7.5 +3.3.5 diff --git a/CODEOWNERS b/CODEOWNERS index 4bbc6f01f99..787cb5dbadf 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -1 +1,3 @@ -* @github/communities-oss-reviewers +* @github/communities-oss-reviewers +articles/legal.md @github/legal-oss +articles/leadership-and-governance.md @github/legal-oss diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 5833ae49be5..419c8a40892 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -47,7 +47,7 @@ threatening, offensive, or harmful. This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of -representing a project or community includes using an official project e-mail +representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d4c334a2ac6..d5ff9d8a10f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,23 +41,42 @@ If you'd like to contribute, start by searching through the [pull requests](http If you don't see your idea listed, and you think it fits into the goals of this guide, open a pull request. +## 💡 Quick Tip for Beginners + +1. Always create a new branch for your changes. +2. Write clear commit messages. +3. Test your changes locally before submitting a PR. +4. Follow the style guide. +5. Be patient during reviews. + ## Style guide If you're writing content, see the [style guide](./docs/styleguide.md) to help your prose match the rest of the guides. ## Setting up your environment -This site is powered by [Jekyll](https://jekyllrb.com/). Running it on your local machine requires a working [Ruby](https://www.ruby-lang.org/en/) installation with [Bundler](https://bundler.io/). +This site is powered by [Jekyll](https://jekyllrb.com/). Running it on your local machine requires a working [Ruby](https://www.ruby-lang.org/en/) installation with [Bundler](https://bundler.io/) along with [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). + +Once you have that set up: + +1. Grant execution permissions to the scripts: + +```bash +chmod +x script/bootstrap +chmod +x script/server +``` -Once you have that set up, run: +2. Execute the scripts: - script/bootstrap - script/server +```bash +./script/bootstrap +./script/server +``` …and open in your web browser. ## Community -Discussions about the Open Source Guides take place on this repository's [Issues](https://github.com/github/opensource.guide/issues) and [Pull Requests](https://github.com/github/opensource.guide/pulls) sections. Anybody is welcome to join these conversations. +Discussions about the Open Source Guides take place on this repository's [Pull Requests](https://github.com/github/opensource.guide/pulls) section. Anybody is welcome to join these conversations. Wherever possible, do not take these conversations to private channels, including contacting the maintainers directly. Keeping communication public means everybody can benefit and learn from the conversation. diff --git a/Gemfile b/Gemfile index a76c33fb51c..e3066762e33 100644 --- a/Gemfile +++ b/Gemfile @@ -1,8 +1,9 @@ source "https://rubygems.org" -gem "github-pages", group: :jekyll_plugins +gem "github-pages", "~> 232", group: :jekyll_plugins +gem "nokogiri", ">= 1.18.3" group :test do - gem "html-proofer", "~> 3.19.4" + gem "html-proofer" gem "rake" end diff --git a/Gemfile.lock b/Gemfile.lock new file mode 100644 index 00000000000..493a509ffea --- /dev/null +++ b/Gemfile.lock @@ -0,0 +1,364 @@ +GEM + remote: https://rubygems.org/ + specs: + Ascii85 (2.0.1) + activesupport (7.2.3.1) + base64 + benchmark (>= 0.3) + bigdecimal + concurrent-ruby (~> 1.0, >= 1.3.1) + connection_pool (>= 2.2.5) + drb + i18n (>= 1.6, < 2) + logger (>= 1.4.2) + minitest (>= 5.1, < 6) + securerandom (>= 0.3) + tzinfo (~> 2.0, >= 2.0.5) + addressable (2.9.0) + public_suffix (>= 2.0.2, < 8.0) + afm (1.0.0) + async (2.43.0) + console (~> 1.29) + fiber-annotation + io-event (~> 1.11) + base64 (0.3.0) + benchmark (0.5.0) + bigdecimal (3.3.1) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.12.2) + colorator (1.1.0) + commonmarker (0.23.10) + concurrent-ruby (1.3.7) + connection_pool (3.0.2) + console (1.37.0) + fiber-annotation + fiber-local (~> 1.1) + json + csv (3.3.0) + dnsruby (1.72.2) + simpleidn (~> 0.2.1) + drb (2.2.3) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + ethon (0.18.0) + ffi (>= 1.15.0) + logger + eventmachine (1.2.7) + execjs (2.9.1) + faraday (2.14.3) + faraday-net_http (>= 2.0, < 3.5) + json + logger + faraday-net_http (3.4.4) + net-http (~> 0.5) + ffi (1.17.4-aarch64-linux-gnu) + ffi (1.17.4-aarch64-linux-musl) + ffi (1.17.4-arm-linux-gnu) + ffi (1.17.4-arm-linux-musl) + ffi (1.17.4-arm64-darwin) + ffi (1.17.4-x64-mingw-ucrt) + ffi (1.17.4-x86-linux-gnu) + ffi (1.17.4-x86-linux-musl) + ffi (1.17.4-x86_64-darwin) + ffi (1.17.4-x86_64-linux-gnu) + ffi (1.17.4-x86_64-linux-musl) + fiber-annotation (0.2.0) + fiber-local (1.1.0) + fiber-storage + fiber-storage (1.0.1) + forwardable-extended (2.6.0) + gemoji (4.1.0) + github-pages (232) + github-pages-health-check (= 1.18.2) + jekyll (= 3.10.0) + jekyll-avatar (= 0.8.0) + jekyll-coffeescript (= 1.2.2) + jekyll-commonmark-ghpages (= 0.5.1) + jekyll-default-layout (= 0.1.5) + jekyll-feed (= 0.17.0) + jekyll-gist (= 1.5.0) + jekyll-github-metadata (= 2.16.1) + jekyll-include-cache (= 0.2.1) + jekyll-mentions (= 1.6.0) + jekyll-optional-front-matter (= 0.3.2) + jekyll-paginate (= 1.1.0) + jekyll-readme-index (= 0.3.0) + jekyll-redirect-from (= 0.16.0) + jekyll-relative-links (= 0.6.1) + jekyll-remote-theme (= 0.4.3) + jekyll-sass-converter (= 1.5.2) + jekyll-seo-tag (= 2.8.0) + jekyll-sitemap (= 1.4.0) + jekyll-swiss (= 1.0.0) + jekyll-theme-architect (= 0.2.0) + jekyll-theme-cayman (= 0.2.0) + jekyll-theme-dinky (= 0.2.0) + jekyll-theme-hacker (= 0.2.0) + jekyll-theme-leap-day (= 0.2.0) + jekyll-theme-merlot (= 0.2.0) + jekyll-theme-midnight (= 0.2.0) + jekyll-theme-minimal (= 0.2.0) + jekyll-theme-modernist (= 0.2.0) + jekyll-theme-primer (= 0.6.0) + jekyll-theme-slate (= 0.2.0) + jekyll-theme-tactile (= 0.2.0) + jekyll-theme-time-machine (= 0.2.0) + jekyll-titles-from-headings (= 0.5.3) + jemoji (= 0.13.0) + kramdown (= 2.4.0) + kramdown-parser-gfm (= 1.1.0) + liquid (= 4.0.4) + mercenary (~> 0.3) + minima (= 2.5.1) + nokogiri (>= 1.16.2, < 2.0) + rouge (= 3.30.0) + terminal-table (~> 1.4) + webrick (~> 1.8) + github-pages-health-check (1.18.2) + addressable (~> 2.3) + dnsruby (~> 1.60) + octokit (>= 4, < 8) + public_suffix (>= 3.0, < 6.0) + typhoeus (~> 1.3) + hashery (2.1.2) + html-pipeline (2.14.3) + activesupport (>= 2) + nokogiri (>= 1.4) + html-proofer (5.2.2) + addressable (~> 2.3) + async (~> 2.1) + benchmark (~> 0.5) + nokogiri (~> 1.13) + pdf-reader (~> 2.11) + rainbow (~> 3.0) + typhoeus (~> 1.3) + yell (~> 2.0) + zeitwerk (~> 2.5) + http_parser.rb (0.8.0) + i18n (1.14.8) + concurrent-ruby (~> 1.0) + io-event (1.19.4) + jekyll (3.10.0) + addressable (~> 2.4) + colorator (~> 1.0) + csv (~> 3.0) + em-websocket (~> 0.5) + i18n (>= 0.7, < 2) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 2.0) + kramdown (>= 1.17, < 3) + liquid (~> 4.0) + mercenary (~> 0.3.3) + pathutil (~> 0.9) + rouge (>= 1.7, < 4) + safe_yaml (~> 1.0) + webrick (>= 1.0) + jekyll-avatar (0.8.0) + jekyll (>= 3.0, < 5.0) + jekyll-coffeescript (1.2.2) + coffee-script (~> 2.2) + coffee-script-source (~> 1.12) + jekyll-commonmark (1.4.0) + commonmarker (~> 0.22) + jekyll-commonmark-ghpages (0.5.1) + commonmarker (>= 0.23.7, < 1.1.0) + jekyll (>= 3.9, < 4.0) + jekyll-commonmark (~> 1.4.0) + rouge (>= 2.0, < 5.0) + jekyll-default-layout (0.1.5) + jekyll (>= 3.0, < 5.0) + jekyll-feed (0.17.0) + jekyll (>= 3.7, < 5.0) + jekyll-gist (1.5.0) + octokit (~> 4.2) + jekyll-github-metadata (2.16.1) + jekyll (>= 3.4, < 5.0) + octokit (>= 4, < 7, != 4.4.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-mentions (1.6.0) + html-pipeline (~> 2.3) + jekyll (>= 3.7, < 5.0) + jekyll-optional-front-matter (0.3.2) + jekyll (>= 3.0, < 5.0) + jekyll-paginate (1.1.0) + jekyll-readme-index (0.3.0) + jekyll (>= 3.0, < 5.0) + jekyll-redirect-from (0.16.0) + jekyll (>= 3.3, < 5.0) + jekyll-relative-links (0.6.1) + jekyll (>= 3.3, < 5.0) + jekyll-remote-theme (0.4.3) + addressable (~> 2.0) + jekyll (>= 3.5, < 5.0) + jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) + rubyzip (>= 1.3.0, < 3.0) + jekyll-sass-converter (1.5.2) + sass (~> 3.4) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-sitemap (1.4.0) + jekyll (>= 3.7, < 5.0) + jekyll-swiss (1.0.0) + jekyll-theme-architect (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-cayman (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-dinky (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-hacker (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-leap-day (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-merlot (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-midnight (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-minimal (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-modernist (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-primer (0.6.0) + jekyll (> 3.5, < 5.0) + jekyll-github-metadata (~> 2.9) + jekyll-seo-tag (~> 2.0) + jekyll-theme-slate (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-tactile (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-time-machine (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-titles-from-headings (0.5.3) + jekyll (>= 3.3, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + jemoji (0.13.0) + gemoji (>= 3, < 5) + html-pipeline (~> 2.2) + jekyll (>= 3.0, < 5.0) + json (2.21.1) + kramdown (2.4.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.9.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + logger (1.7.0) + mercenary (0.3.6) + mini_portile2 (2.8.9) + minima (2.5.1) + jekyll (>= 3.5, < 5.0) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + minitest (5.27.0) + net-http (0.9.1) + uri (>= 0.11.1) + nokogiri (1.19.4) + mini_portile2 (~> 2.8.2) + racc (~> 1.4) + nokogiri (1.19.4-aarch64-linux-gnu) + racc (~> 1.4) + nokogiri (1.19.4-aarch64-linux-musl) + racc (~> 1.4) + nokogiri (1.19.4-arm-linux-gnu) + racc (~> 1.4) + nokogiri (1.19.4-arm-linux-musl) + racc (~> 1.4) + nokogiri (1.19.4-arm64-darwin) + racc (~> 1.4) + nokogiri (1.19.4-x64-mingw-ucrt) + racc (~> 1.4) + nokogiri (1.19.4-x86_64-darwin) + racc (~> 1.4) + nokogiri (1.19.4-x86_64-linux-gnu) + racc (~> 1.4) + nokogiri (1.19.4-x86_64-linux-musl) + racc (~> 1.4) + octokit (4.25.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + pdf-reader (2.15.1) + Ascii85 (>= 1.0, < 3.0, != 2.0.0) + afm (>= 0.2.1, < 2) + hashery (~> 2.0) + ruby-rc4 + ttfunk + public_suffix (5.1.1) + racc (1.8.1) + rainbow (3.1.1) + rake (13.4.2) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) + ffi (~> 1.0) + rexml (3.4.2) + rouge (3.30.0) + ruby-rc4 (0.1.5) + rubyzip (2.3.2) + safe_yaml (1.0.5) + sass (3.7.4) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + sawyer (0.9.2) + addressable (>= 2.3.5) + faraday (>= 0.17.3, < 3) + securerandom (0.4.1) + simpleidn (0.2.3) + terminal-table (1.8.0) + unicode-display_width (~> 1.1, >= 1.1.1) + ttfunk (1.8.0) + bigdecimal (~> 3.1) + typhoeus (1.6.0) + ethon (>= 0.18.0) + tzinfo (2.0.6) + concurrent-ruby (~> 1.0) + unicode-display_width (1.8.0) + uri (1.1.1) + webrick (1.8.2) + yell (2.2.2) + zeitwerk (2.8.2) + +PLATFORMS + aarch64-linux-gnu + aarch64-linux-musl + arm-linux + arm-linux-gnu + arm-linux-musl + arm64-darwin + x64-mingw-ucrt + x86-linux + x86-linux-gnu + x86-linux-musl + x86_64-darwin + x86_64-linux + x86_64-linux-gnu + x86_64-linux-musl + +DEPENDENCIES + github-pages (~> 232) + html-proofer + nokogiri (>= 1.18.3) + rake + +BUNDLED WITH + 2.5.19 diff --git a/README.md b/README.md index fa135ab3dbd..fb0d6d4df1e 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,9 @@ Content is released under [CC-BY-4.0](https://creativecommons.org/licenses/by/4. ## Acknowledgments -The initial release of these guides were authored by **[@nayafia][1], [@bkeepers][2], [@stephbwills][3],** and **[@mlinksva][4]**. +The initial release of these guides was authored by **[@nayafia][1], [@bkeepers][2], [@stephbwills][3],** and **[@mlinksva][4]**. -Thanks to **[@aitchabee][5], [@benbalter][6], [@brettcannon][7], [@caabernathy][8], [@coralineada][9], [@dmleong][10], [@ericholscher][11], [@gr2m][12], [@janl][13], [@jessfraz][14], [@joshsimmons][15], [@kfogel][16], [@kytrinyx][17], [@lee-dohm][18], [@mikeal][19], [@mikemcquaid][20], [@nathansobo][21], [@nruff][22], [@nsqe][23], [@orta][24], [@parkr][25], [@shazow][26], [@steveklabnik][27],** and **[@wooorm][28]** for lending their valuable input and expertise leading up to the initial release, and to **[@sophshep][29]** and **[@jeejkang][30]** for designing and illustrating the guides. +Thanks to **[@aitchabee][5], [@benbalter][6], [@brettcannon][7], [@caabernathy][8], [@coralineada][9], [@dmleong][10], [@ericholscher][11], [@gr2m][12], [@janl][13], [@jessfraz][14], [@bluesomewhere][15], [@kfogel][16], [@kytrinyx][17], [@lee-dohm][18], [@mikeal][19], [@mikemcquaid][20], [@nathansobo][21], [@nruff][22], [@nsqe][23], [@orta][24], [@parkr][25], [@shazow][26], [@steveklabnik][27],** and **[@wooorm][28]** for lending their valuable input and expertise leading up to the initial release, and to **[@sophshep][29]** and **[@jeejkang][30]** for designing and illustrating the guides. ## Disclaimer While we've got advice about running an open source project, we're not lawyers. Be sure to read our [disclaimer](notices.md#legal-disclaimer) before diving in. @@ -39,7 +39,7 @@ While we've got advice about running an open source project, we're not lawyers. [12]:https://github.com/gr2m [13]:https://github.com/janl [14]:https://github.com/jessfraz -[15]:https://github.com/joshsimmons +[15]:https://github.com/bluesomewhere [16]:https://github.com/kfogel [17]:https://github.com/kytrinyx [18]:https://github.com/lee-dohm diff --git a/_articles/accessibility-best-practices-for-your-project.md b/_articles/accessibility-best-practices-for-your-project.md new file mode 100644 index 00000000000..18981cffd1b --- /dev/null +++ b/_articles/accessibility-best-practices-for-your-project.md @@ -0,0 +1,302 @@ +--- +lang: en +untranslated: true +title: Accessibility Best Practices for Your Project +description: Practical, actionable steps to make your open source project usable by everyone, especially people with disabilities. +class: accessibility-best-practices +order: -1 +image: /assets/images/cards/accessibility-best-practices.png +--- + +Accessibility (often shortened to _a11y_) means people can use your project regardless of disability, assistive technology, environment, or device. It includes - but isn't limited to - support for screen readers, keyboard-only navigation, captions/transcripts, sufficient color contrast, and clear content structure. + +## Partner with people with disabilities + +**"Nothing about us without us"** - The most important thing you can do for accessibility is to center the people it serves. Users, contributors, and testers with disabilities understand barriers in ways that guidelines and automated tools cannot. Seek out their lived experience early and often. + +### Put it into practice + +Decisions made without the people affected by them tend to miss the mark. Building with people with disabilities, rather than for them, leads to better software for everyone. + +Here are a few ways to center lived experience: + +* Invite contributors with disabilities into design discussions, not just bug triage. +* Involve people with disabilities for usability testing and feedback when you can. +* Listen when someone describes how they use your project, even when it challenges your assumptions. +* Treat accessibility reports as expertise, not complaints - they may represent more people than you think. + +### Accessibility benefits everyone + +* **It impacts a lot of people.** An estimated 1.3 billion people (1 in 6) experience significant disability, according to the [World Health Organization](https://www.who.int/news-room/fact-sheets/detail/disability-and-health). +* **It's part of quality.** Accessible products tend to be more usable for everyone. +* **It reduces support load.** Clearer UI and docs mean fewer confused users. +* **It expands your contributor base.** Assistive tech users can more fully participate. +* **It drives innovation.** Designing for diverse needs often leads to features that benefit everyone (like captions, voice control, and dark mode all began as accessibility solutions). +* **It's often required.** Many orgs (and some governments) require accessibility for procurement and compliance. +* **Our future is uncertain.** Nobody today can be confident about the abilities we will have tomorrow. + +## Start with an accessibility statement + +Before diving into code, take a moment to document your project's accessibility commitment. An accessibility statement signals to users and contributors that accessibility is a priority, not an afterthought. For guidance, refer to the [W3C's Developing an Accessibility Statement](https://www.w3.org/WAI/planning/statements/). + +Add a clear statement that sets expectations and makes it easy for users to report issues. You can either add an accessibility section directly in your README, or create a dedicated **ACCESSIBILITY.md** file and link to it from your README for visibility. Refer to this [ACCESSIBILITY.md example](https://github.com/open-source-accessibility/accessibility-toolkit/blob/main/ACCESSIBILITY.md). + +### Goals + +* State measurable goals and guidelines (like [WCAG AA](https://www.w3.org/TR/WCAG22/#wcag-2-layers-of-guidance) where feasible). +* Define primary priorities, and how you meet them (keyboard and screen reader support, captions and transcripts, etc.). +* Define any known limitations, and alternative workarounds (if present). + +### Contributor requirements + +Establish clear guardrails so contributors know what's expected: + +* **Testing:** All UI changes must be tested with an accessibility testing tool (like [Axe DevTools](https://www.deque.com/axe/devtools/extension/#:~:text=Try%20Axe%20DevTools%20Extension%20in%20your%20browser%20of%20choice)). +* **Documentation:** Follow your project's accessibility guidelines for components like SVGs, images, and interactive elements. +* **CI/CD:** PRs will fail if they introduce violations detected by the accessibility linting workflow. + +### Supported environments + +* List platforms you support (web, mobile web, iOS, Android, terminal/CLI, desktop apps). +* List any partial-support notes. + +### Reporting accessibility bugs + +* Ask reporters to open issues using the accessibility issue template. +* **Tip:** Set expectations honestly (like "We're working on this - tracking in ISSUE-123"); acknowledge reports and provide follow-up or workaround when possible. + +#### Why separate accessibility from your general issue process? + +Users have come to expect a dedicated accessibility statement and reporting path - it's a well-established convention in the private sector and across government sites, and many users look for it first when they hit a barrier. Keeping accessibility distinct from your general issue flow matters because: + +* **Impact is time-sensitive.** An accessibility bug can block a user from using your project at all, not just inconvenience them. A dedicated path helps these reported issues get triaged faster. +* **Context is different.** Accessibility reported issues need specific information (assistive tech, OS, browser, severity) that a generic bug template doesn't prompt for. +* **It signals commitment.** A visible, separate statement tells users and contributors that accessibility is a first-class concern, not something folded into "other bugs." +* **Reporters may use assistive technology to file the report itself.** A clear, predictable process (a known file, a known label, a known template) reduces friction for the people most affected. + +## Make docs accessible by default + +Documentation is often the first "UI" users touch. Make sure everyone can read it. + +### Structure and semantics + +* Use a **logical heading hierarchy** and don't skip levels (`#`, `##`, `###`, `####`, `#####`, and `######`). +* Use **unique, descriptive link text** ("Read the contributing guide" instead of "click here"). +* Use plain language, avoiding jargon and expanding any abbreviation the first time it is used. +* [Use **real lists**](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#lists) over manually typed numbering. +* Keep **help and navigation in consistent locations** across pages so users can find them predictably. +* Avoid conveying meaning only through position or styling ("see the red text on the right"). + +### Images, diagrams and videos + +* Provide meaningful **alternative text** (often shortened to "alt text") for images (refer to the [W3C's alt Decision Tree](https://www.w3.org/WAI/tutorials/images/decision-tree/)). +* Instead of using images of text, use real text whenever possible. +* For complex images (like architecture diagrams), include an additional **text alternative** nearby (bullets or a short explanation). +* If you publish demos, tutorials, talks, or release videos: + * Provide **captions** (prefer human-edited when possible). + * Provide a **transcript**. + * Avoid auto-playing audio and video. + * Describe important on-screen actions verbally. + +### Tables + +* Use tables only for tabular data, not for layout. +* Provide **header cells** to associate column and row headers with data cells. +* Provide a **caption or summary** describing the table's purpose. + +### Code blocks + +* Keep lines reasonably short (wrapping helps readability). +* Don't rely on color highlighting alone to indicate meaning. +* Explain inline what the code does and what success looks like. + +## Design accessible interfaces + +If your project has a web UI, these high-impact defaults will help all users. + +### Keyboard support + +* Everything interactive should be reachable and usable with **keyboard only**. +* Ensure a **visible focus indicator** (don't remove focus outlines unless you replace them). +* Maintain a logical **tab order** that matches the visual layout. +* Don't trap focus inside components unless you intentionally manage focus (like modal dialogs) and provide a way out. + +### Semantics first + +* Use **native HTML** elements (`

`, `