This document defines the development workflow, naming conventions, and repository rules.
All contributors are expected to follow these rules to ensure consistency, clarity, and fast iteration.
All work MUST follow this flow:
Issue → Branch → Pull Request → Review → Merge (squash via merge queue)
- Every task MUST be tracked via a GitHub issue
- No work MUST be performed without an associated issue
- Issue titles MUST describe the problem or goal
- Issue titles MUST NOT use commit-style prefixes (e.g.
feat(...),fix(...))
Examples:
- Gas calculation overflows on large inputs
- Add withdrawal flow for vara.eth bridge
Each issue MUST include:
type:*scope:*
The following labels SHOULD be added when applicable:
priority:*size:*
An issue is considered in progress when it is assigned.
Unassigned issues are considered open for anyone to take.
Branches MUST follow the format:
/
Examples:
- pp/impl-web
- ab/fix-gas-overflow
- jd/add-withdrawal-flow
A Pull Request MUST be created as Draft if:
- work is incomplete
- the PR is a proof-of-concept (PoC)
- early feedback is required
A Pull Request MUST be marked as Ready for review when:
- implementation is complete
- the PR is ready for full review
- Draft — work in progress or PoC (not ready for review)
- Ready for review — ready for review
- Changes requested — issues identified, updates required
- Approved — ready to merge (subject to CI)
All Pull Request titles MUST follow Conventional Commits:
(/): !:
- feat
- fix
- refactor
- docs
- test
- chore
- gear
- vara
- vara.eth
- programs
Breaking changes MUST be indicated using !:
refactor(programs)!: remove deprecated API
Allowed labels:
- type: *
- scope: *
- priority: critical | important | normal | backlog
- size: S | M | L | XL
- ai-friendly (optional)
- ai-generated (optional)
- critical — must be addressed immediately (production, security, or consensus impact)
- important — should be addressed soon; blocks meaningful progress or upcoming release
- normal — standard planned work
- backlog — low priority; no immediate action required
- S — small task (hours)
- M — medium task (1–2 days)
- L — large task (several days)
- XL — very large task; SHOULD be split if possible
Allowed labels:
- type: *
- scope: *
- ci: *
- ai-friendly (optional)
- ai-generated (optional)
- pr: do-not-merge
priority:*MUST NOT be used on Pull Requestssize:*MUST NOT be used on Pull Requests
CI labels are used ONLY on Pull Requests.
Available labels:
- ci: docker
- ci: windows
- ci: macos
- ci: linux-aarch64
- ci: release
- ci: production
- ci: full
- ci: release → runs
cargo --release - ci: production → runs
cargo --profile production - ci: full → runs full CI matrix (all platforms and profiles)
CI labels are reactive and may be modified automatically by CI:
- labels MAY be added or removed based on PR title or other labels
typeandscopeMAY be derived from PR titleci: fulloverrides all otherci:*labels- redundant labels MAY be removed automatically
- No more than two CI labels SHOULD be used per PR
- If more coverage is required,
ci: fullSHOULD be used
- All Pull Requests MUST go through merge queue
- All merges are performed via squash merge
- The Pull Request title MUST be used as the final commit message
If the author agrees with a review comment:
- the author MUST push the required changes
- the author MUST resolve the conversation
If the author disagrees:
- the author MUST provide reasoning
- agreement MUST be reached with the reviewer
- the reviewer MUST resolve the conversation if they withdraw the comment
If changes are pushed after approval:
- the author MUST notify the reviewer if the changes are non-trivial
- the author MUST request re-review if behavior or logic has changed
- silent changes after approval MUST be avoided
For breaking or risky changes, re-review is REQUIRED.
The Pull Request MUST NOT be merged while this label is present.
This label is enforced via CI and blocks merge queue.
Indicates that the issue or Pull Request was created entirely by an AI agent, without direct human authorship.
This label MUST be applied when:
- the issue was opened by an AI agent autonomously
- the PR was authored and submitted by an AI agent end-to-end
Human review of ai-generated issues and Pull Requests is REQUIRED before merging.
Indicates that the task is suitable for AI-assisted work.
This label MAY be applied to both issues and Pull Requests.
On an issue, it signals that contributors are encouraged to point their AI agents at it — the task is scoped well enough for autonomous implementation.
This includes tasks that:
- can be fully implemented by AI
- can be reliably reviewed by AI
- have low architectural or consensus risk
This label is used to improve development speed, not to reduce quality standards.
- A Pull Request MUST represent a single logical change
- Large Pull Requests SHOULD be avoided
- Tests SHOULD be added or updated when modifying logic
- Documentation SHOULD be updated when necessary
- Draft PRs SHOULD be used early to share progress and gather feedback
Issue = problem or goal Pull Request = implementation
Labels = classification CI labels = execution control
Pull Request title = source of truth for release notes
All .rs source files MUST include a license header as the first two lines:
// Copyright (C) Gear Technologies Inc.
// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0A blank line MUST follow the header before any code or module-level comments.
Files derived from third-party sources MUST preserve the original copyright line and MUST NOT include the Gear copyright line:
// Copyright (C) 2017-2024 Parity Technologies.
// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0The LICENSE file in the repository root is the authoritative license text.
This process is intentionally minimal and designed for a small, fast-moving team.