Contribution Workflow

GitHub Fork & PR Feature Branching Pre-Commit Validation Automated CI

This guide details the complete step-by-step process for contributing code, bug fixes, or documentation to any CloudRader project.

Contribution Lifecycle

flowchart TD
    Fork["1. Fork & Clone Repository"] --> Branch["2. Create Feature Branch<br/>(feat/..., fix/...)"]
    Branch --> Setup["3. Setup Environment<br/>(make install / uv sync)"]
    Setup --> Code["4. Implement & Format<br/>(Ruff / ESLint)"]
    Code --> Check["5. Validate Locally<br/>(make check)"]
    Check --> Commit["6. Commit Changes<br/>(Conventional Commits)"]
    Commit --> Push["7. Push & Open Pull Request"]
    Push --> CI["8. CI Checks & Code Review"]
    CI --> Merge["9. Merged into main!"]

Step 1: Fork and Clone the Repository

Navigate to the target CloudRader repository on GitHub (e.g., CloudRader/docs) and click Fork.

Clone your personal fork to your local workstation:

git clone https://github.com/<your-username>/<repo-name>.git
cd <repo-name>

Configure the upstream remote to keep your fork synchronized:

git remote add upstream https://github.com/CloudRader/<repo-name>.git
git fetch upstream

Step 2: Create a Feature Branch

Always create a dedicated topic branch branched off the latest upstream/main:

git checkout main
git pull upstream main
git checkout -b <branch-name>

Branch Naming Conventions

Use descriptive branch names prefixed by the change type:

Branch Pattern	Purpose	Example
`feat/<name>`	New user-facing feature or capability	`feat/asset-qr-generation`
`fix/<name>`	Bug fix or error resolution	`fix/null-response-handling`
`docs/<name>`	Documentation updates or tutorials	`docs/refactor-contributing-guide`
`refactor/<name>`	Code refactoring without behavioral change	`refactor/service-database-layer`
`chore/<name>`	Tooling, dependencies, or repository hygiene	`chore/update-pre-commit-hooks`

Step 3: Local Environment Setup

CloudRader repositories use standard automation via Makefile and modern tooling:

Install Dependencies: Install locked dependencies using make:
```
make install
```
(In Python repositories, this invokes uv sync under the hood).
Install Pre-Commit Hooks: Ensure git hooks are active to catch formatting issues early:
```
make pre-commit-install
```

Step 4: Develop, Test & Format

Make focused, atomic changes following the Development Standards.
Preview documentation changes locally:
```
make serve
```
The local live preview runs at http://localhost:8000.
Run linters and formatting checks:
```
make pre-commit
```

Fast Feedback

Pre-commit hooks automatically check trailing whitespace, final newlines, YAML/TOML validity, and file sizes. Running them before committing prevents failed CI runs.

Step 5: Validate Locally with `make check`

Before committing or opening a pull request, run the full validation suite:

make check

This target performs:

A clean, warnings-free build of the application or static site (make build).
All configured pre-commit and linter checks (make pre-commit).

Step 6: Commit and Push Changes

Stage your modified files:
```
git add .
```

Author a concise commit message adhering to Conventional Commits:

git commit -m "docs(contributing): refactor guide with lifecycle diagrams and standards matrix"

Push the feature branch to your GitHub fork:
```
git push -u origin <branch-name>
```

Step 7: Open a Pull Request

Visit your fork on GitHub and click Compare & pull request.
Ensure the base repository is CloudRader/<repo-name> and the base branch is main.
Provide a clear summary:
- What: Describe the changes made.
- Why: Explain the problem solved or motivation.
- Verification: Mention the tests and validation commands executed (make check).
- Issues: Link relevant issues using GitHub keywords (e.g., Closes #12).
Wait for automated CI checks to complete and address any reviewer feedback.

Reporting Bugs & Requesting Features

If you encounter a problem or have an idea for an enhancement, please open an issue:

Bug Reports: Include your environment details (OS, container engine, browser), exact steps to reproduce, expected versus actual behavior, and relevant error logs.
Feature Requests: Describe the specific use case, explain why existing functionality does not address it, and outline your proposed solution.