Alpha 2 Software: ATR is available as Alpha software. You can test the release process. Actual releases can be downloaded and committed to svn.

3.10. How to contribute

Up: 3. Developer guide

Prev: 3.9. Code conventions

Next: 3.11. Authentication security

Sections:

Quick start

For the contribution workflow, see CONTRIBUTING.md in the repository root.

That guide covers:

  • Development setup
  • Pull request workflow
  • Running tests
  • Code standards summary

IMPORTANT: New contributors must introduce themselves on the development mailing list first, to deter spam. Please do not submit a PR until you have introduced yourself.

The rest of this page covers detailed policies and guidelines.

Commit message style

We follow a consistent style for commit messages. The first line (subject line) should:

  • Use the imperative mood. Complete the sentence "If applied, this commit will..."
  • Use sentence case. Start with a capital letter, no full stop at the end.
  • Use articles before nouns. Write "Fix a bug", not "Fix bug".
  • Be specific and descriptive. Prefer "Fix a bug in vote resolution for tied votes" to "Fix a bug".
  • Keep it concise. Aim for 50-72 characters.

Good examples:

Add distribution platform validation to the compose phase
Fix a bug with sorting version numbers containing release candidates
Move code to delete releases to the storage interface
Update dependencies

Poor examples:

fixed stuff
Updated the code.
refactoring vote resolution logic

Most commits do not need a body. For complex changes, add a body separated by a blank line explaining what and why (not how). We typically use asterisk-itemized lists.

Contributing documentation

ATR documentation lives in atr/docs/ as Markdown files. When adding or modifying documentation, it is important to understand how the documentation is built.

The file atr/docs/index.md contains a table of contents that acts as the source of truth for the documentation build system. The scripts/docs_build.py script reads this file to discover all documentation pages, generate navigation links, and validate that everything is consistent.

When you add a new documentation file, you must also add an entry to the table of contents in index.md. The build will fail if any .md files exist in atr/docs/ that are not listed in the table of contents, or if the table of contents references files that do not exist.

ASF contribution policies

As an Apache Software Foundation project, ATR follows standard ASF contribution and licensing policies.

Contributor License Agreement

Before your first contribution, you must sign the Apache Individual Contributor License Agreement (ICLA). This is a one-time requirement.

The ICLA grants the ASF the right to distribute and build upon your work, while you retain full rights to use your contributions for any other purpose. It is not a copyright assignment. See the ASF new committers guide for submission instructions.

If your employer holds rights to your work, you may also need a Corporate Contributor License Agreement (CCLA). Consult your employer to determine if this is necessary.

Licensing

All contributions are licensed under the Apache License 2.0. By submitting a pull request, you agree to this license.

Third-party code or dependencies must be compatible with Apache License 2.0:

Code of conduct

All contributors must follow the ASF Code of Conduct.

Special considerations for ATR

ATR is developed by ASF Tooling, an ASF initiative rather than a top-level project (TLP). This affects governance and development processes. More significantly, ATR has stringent security requirements.

Security focus

The primary goal of ATR is to deter and minimize supply chain attacks on ASF software releases. We scrutinize all contributions for potential vulnerabilities.

When contributing:

  • Follow secure coding practices. Avoid injection attacks, cross-site scripting, insecure deserialization.
  • Validate all inputs and sanitize all outputs.
  • Use established libraries for cryptographic or security-sensitive functionality. Prefer well-established, independently audited, actively maintained libraries.
  • Consider security implications. If unsure, ask the team for guidance.
  • Report vulnerabilities responsibly. Do not open public issues for security problems. Follow the ASF security reporting process.

High quality standards

Because of ATR's critical nature, we maintain very high code quality standards. The review process may take longer than expected, and we may request extensive changes. Our goal is to keep ATR as secure and reliable as possible.

Access controls

We strongly encourage all contributors to enable two-factor authentication on their GitHub accounts, preferably with a passkey.

Getting help

Alternative: email patches

If you prefer not to use GitHub, you can email patches using standard Git patch formatting.