Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
136 lines (103 loc) · 4.88 KB

CONTRIBUTING.md

File metadata and controls

136 lines (103 loc) · 4.88 KB
Raw

Contributing Guide

We welcome contributions to the azure-functions-validation project.

Branch Strategy

Use GitHub Flow and branch from main.

Recommended branch prefixes:

  • feat/ for new features
  • fix/ for bug fixes
  • docs/ for documentation-only changes
  • chore/ for tooling and maintenance
  • ci/ for workflow updates

Development Workflow

  1. Create a branch from main. 
    git checkout main
git pull origin main
git checkout -b feat/your-feature-name
  2. Write code and tests.
  3. Run the local quality gate. 
    make check-all
  4. Push and create a pull request. 
    git push origin feat/your-feature-name

Project Commands

make format      # Format code with ruff
make lint        # Lint with ruff
make typecheck   # Type check with mypy
make test        # Run tests
make cov         # Run tests with coverage
make check-all   # Run the full local gate

GitHub Actions Pinning

All external uses: references in .github/workflows/ MUST pin to a full 40-character commit SHA with a trailing comment documenting the released version or channel. Example:

- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

This applies to first-party (actions/*, github/*, azure/*) and third-party Actions alike.

Rationale. Mutable tags (including immutable-looking version tags like @v6.0.1) can be retroactively moved by an attacker who gains write access to the upstream repository. The tj-actions/changed-files compromise (CVE-2025-30066, March 2025) demonstrated this exact failure mode: ~23,000 repositories had their CI secrets exfiltrated, and only workflows that pinned to a commit SHA were safe. GitHub's own guidance now identifies SHA pinning as the only way to use an Action as an immutable release, and OpenSSF Scorecard's Pinned-Dependencies check flags anything weaker as Medium-risk.

Dependabot updates SHA-pinned references on the configured schedule and keeps the trailing version comment in sync, so the human-readable context never drifts from the pinned commit.

Approved exceptions. The following mutable refs are the only ones permitted in this repository and are flagged with an inline comment at the call site:

  • pypa/gh-action-pypi-publish@release/v1 — PyPA-maintained stable release channel; this pinning style is explicitly recommended upstream.
  • Local composite actions (uses: ./...) — versioned with the repo.

When adding a new external Action, resolve the SHA with git ls-remote <repo-url> 'refs/tags/<tag>^{}'. The trailing ^{} dereferences the ref to its target commit; without it, an annotated tag returns the tag-object SHA instead of the commit SHA, and the tag-object SHA is not a valid uses: target.

# Annotated tag — the two forms return *different* SHAs:
git ls-remote https://github.com/Azure/login 'refs/tags/v3.0.0' 'refs/tags/v3.0.0^{}'
# 93381592...   refs/tags/v3.0.0       <- tag object, do NOT pin to this
# 532459ea...   refs/tags/v3.0.0^{}    <- commit, pin to this one

# Lightweight tag — only the non-deref form returns a row, and it is
# already the commit SHA. Always include the `^{}` form anyway so the
# same command works for both tag types:
git ls-remote https://github.com/actions/setup-python 'refs/tags/v6' 'refs/tags/v6^{}'

Single-quote the refs/...^{} argument so the {} and ^ are not interpreted by your shell (notably zsh with EXTENDED_GLOB).

Example Coverage Policy

Examples are part of the supported API experience and should stay verified.

  • Keep one representative example for the minimal validation workflow.
  • Keep one complex example for custom error handling and multi-field validation.
  • Add or update smoke tests whenever an example changes.
  • Prefer lightweight smoke coverage over infrastructure-heavy end-to-end tests.

Commit Message Guidelines

We follow the Conventional Commits specification.

Examples

git commit -m "feat: add OpenAPI 3.1 support"
git commit -m "fix: handle empty request body gracefully"
git commit -m "docs: improve quickstart documentation"
git commit -m "refactor: extract schema builder logic"
git commit -m "chore: update dev dependencies"

Use imperative present tense and keep the message concise.

Deployment

  • A merge to main triggers the production deployment workflow.
  • Deployment status can be tracked from the related GitHub Actions run.

Code of Conduct

Be respectful and inclusive. See our Code of Conduct for details.