Contributing Guidelines

February 4, 2026 · View on GitHub

We're so thankful you're considering contributing to an open source project of the U.S. government! If you're unsure about anything, just ask -- or submit the issue or pull request anyway. The worst that can happen is you'll be politely asked to change something. We appreciate all friendly contributions.

We encourage you to read this project's CONTRIBUTING policy (you are here), its LICENSE, and its README.

Getting Started

Look for issues labeled good-first-issue for good opportunities to contribute. These issues are specifically chosen to help newcomers get involved with the project.

Team Specific Guidelines

Our project maintainers are listed in COMMUNITY.md. They are responsible for reviewing and merging all pull requests. Feel free to tag them in issues or pull requests for assistance.

Building Dependencies

To work on this project, you'll need:

  1. Node.js 20 or later
  2. Go 1.22 or later
  3. SCC tool (installed via go install github.com/boyter/scc/v3@latest)
  4. GitHub CLI (optional, but helpful for testing)

Building the Project

# Clone the repository
git clone https://github.com/DSACMS/automated-codejson-generator.git
cd automated-codejson-generator

# Install dependencies
npm install

# Build the project
npm run bundle

# Run tests
npm test

Validation

The action uses Zod for schema validation, automatically validating code.json in two scenarios:

1. Before Generation

Every time the action generates or updates code.json (via schedule or workflow_dispatch), it validates the output before creating a PR or pushing. If validation fails, no changes are made.

2. On PR Edits

When the pull_request trigger is configured, the action validates code.json whenever it's edited in a PR. This ensures users cannot accidentally merge invalid JSON.

Workflow and Branching

We follow a GitHub Flow–inspired workflow with a protected main branch and a dev integration branch.

  1. Fork the project
  2. Check out the dev branch
  3. Create a feature branch from dev
  4. Write code and tests for your change
  5. Open a pull request from your feature branch into dev
  6. Work with repo maintainers to get your change reviewed and merged into dev
  7. When dev is ready for release, open a pull request from dev into main
  8. Add exactly one release label to the PR:
    • release:patch
    • release:minor
    • release:major
  9. Once the required checks pass, merge the PR into main
    • This triggers automatic versioning, tagging, and GitHub Release creation
  10. Delete your feature branch after merge

Testing Conventions

  • Tests are written using Jest and can be found in the __tests__ directory
  • Run tests with npm test
  • All new features should include corresponding test coverage
  • Test files should follow the naming convention: *.test.ts

Coding Style and Linters

  1. This project uses TypeScript and follows standard TypeScript conventions
  2. We follow the Prettier code formatting rules
  3. ESLint is used for code linting
  4. All code must pass typechecking and linting before being merged
  5. Run npm run lint to check your code

Writing Issues

When creating an issue please try to adhere to the following format:

### Description

Clear description of the issue or feature request

### Expected behavior

What should happen

### Actual behavior

What is happening (for bugs)

### Steps to reproduce

1. Step one
2. Step two
3. Step three

### Additional context

Any other relevant information

Writing Pull Requests

  1. Pull requests should be focused on a single change
  2. Include tests for any new functionality
  3. Update documentation as needed
  4. Follow our commit message format:
feat(scope): description of feature

- Additional details about the change
- Any breaking changes
- Any migration steps required

Reviewing Pull Requests

Pull requests are reviewed by the maintainers listed in COMMUNITY.md. Reviews will check for:

  • Code quality and style
  • Test coverage
  • Documentation updates
  • Breaking changes
  • Security implications

Shipping Releases

Releases are created by maintainers as needed when significant changes are merged. We use semantic versioning for releases.

Documentation

Documentation improvements are always welcome! Please file an issue first to discuss any major changes. Key areas for documentation:

  • README.md updates
  • Code comments
  • Example workflows
  • TypeScript type definitions

Policies

Open Source Policy

We adhere to the CMS Open Source Policy. If you have any questions, just shoot us an email.

Security and Responsible Disclosure Policy

Submit a vulnerability: Vulnerability reports can be submitted through Bugcrowd. Reports may be submitted anonymously. If you share contact information, we will acknowledge receipt of your report within 3 business days.

For more information about our Security, Vulnerability, and Responsible Disclosure Policies, see SECURITY.md.

Public Domain

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication as indicated in LICENSE.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request or issue, you are agreeing to comply with this waiver of copyright interest.