Skip to main content

Contribution Guide

This guide covers the technical process for contributing to the ADG: forking the repository, setting up the development environment, submitting pull requests, and troubleshooting common issues.

For content standards, writing conventions, and formatting requirements, visit the Style Guide.

Contribution workflow:

Code of Conduct​

Please be respectful and constructive in all interactions. This project follows standard open source etiquette. Visit MDN Web Docs: "Open source etiquette" for more standard open source etiquette guidance.

Pull Request Tips​

  1. Fork this repository to a personal GitHub account.

  2. Build a local copy of the documentation from the fork:

       # Download project dependencies
       npm install
       # Review a copy of the docs
       npm start

  3. Install Vale in the development environment.

  4. If using VS Code, install extensions markdownlint and Vale VS Code.

  5. Install typos in the development environment.

  6. Test all changes locally before submitting a pull request:

      # Review typos
      typos
      # Correct typos
      typos --write-changes
      typos -w
      # Check for config errors and/or broken links
      npm run build
      # Check that everything looks correct
      npm start

  7. Pull requests should be complete and self-contained. Don't submit placeholder content or partial entries.

  8. Ideally, pull requests should address an existing issue, but this isn't required.

  9. Don't submit pull requests with lint or Vale errors in the content or code examples.

Commit Message Guidelines​

This project follows the Conventional Commits specification to maintain clear, consistent commit history.

Format​

Each commit message consists of a type, scope, subject, issue number:

<Type>(<Scope>): <Subject> <Issue #>

Type​

Must be one of the following:

  • docs: documentation changes - term entries, examples, explanations
  • fix: bug fixes - broken links, typos, technical inaccuracies
  • style: formatting changes - capitalization, punctuation, Vale fixes
  • refactor: restructuring content without changing meaning
  • chore: maintenance tasks - dependencies, configuration

Scope​

The scope identifies which glossary section the changes impact:

  • glossary term category names:

    • core-concepts
    • api-types-architectures
    • ai-and-apis
    • tools-techniques
    • workflows-methodologies
    • frameworks-strategy
    • writing-style

  • meta documentation and/or styling filenames:

    • config
    • contribution-guide
    • get-started
    • how-glossary-built
    • introduction
    • prompt-templates
    • quick-reference
    • README
    • src / static
    • style-guide

Subject​

  • use present tense - "add" not "added"
  • these are labels, not complete sentences
  • don't capitalize the first letter
  • no period at the end
  • keep it concise - 50 characters or less
  • find issue numbers in the repository's Issues tab
  • reference the issue in the PR description such as - "Resolves Issue #72"

Examples​

# Good commit messages
docs(core-concepts): add HTTP status codes (Issue #123)
fix(tools-techniques): correct cURL link (Issue #125)
style(writing-style): edit capitalization (Issue #141)

# Bad commit messages
Updated files
Fixed stuff
docs: changes

Troubleshooting​

Build directory not empty​

If npm run build fails with an ENOTEMPTY error, the build directory wasn't cleared before the new build started. This happens when a previous build process, file watcher, or Finder window is holding files open.

# Delete the build directory manually, then rebuild
rm -rf build/
npm run build

If the error persists, check for a running dev server in another terminal. Kill that process first, then delete the directory and rebuild:

# Mac/Linux
lsof -ti :3000 | xargs kill
rm -rf build/
npm run build

# Windows
netstat -ano | findstr :3000
# note the PID from the output, then:
taskkill /PID <pid> /F
rmdir /s /q build
npm run build

Build fails locally​

Make sure all software requirements installed correctly. For example, ensure Node.js and npm are up to date. Run npm install in the fork directory, then attempt the build again.

Changes don't appear after pushing to GitHub​

GitHub Pages can take a few minutes to rebuild and deploy. Wait a few minutes, then refresh the site. Clear the browser cache - Ctrl+Shift+Delete on Windows/Linux, Cmd+Shift+Delete on Mac - if changes still don't appear.

Pull request has lint errors​

Run npm run lint locally to identify errors before submission. Most formatting issues can be auto-fixed with npm run lint:fix.

typos flags intentional spelling​

Check the _typos.toml configuration file in the repository root. Add false positives to [default.extend-words] to suppress them. Run typos --config _typos.toml to verify the configuration is loading correctly.

Vale or markdownlint extensions don't appear in VS Code​

Install the extensions from the Visual Studio Code marketplace. Reload VS Code - Ctrl+R on Windows/Linux and Cmd+R on Mac - after installation.

Vale reports errors, but content appears correct​

Check the .vale.ini configuration file in the repository root. Use vale . to run Vale from the command line and observe detailed error output.

MIT License​

By contributing to this project, contributors agree to contribution license under the MIT License; visit the LICENSE for details