THF Climate Developer's Guide

Developer's Guide

Repository Structure

• src/: All source code files.
• tests/: Unit and integration tests.
• README.md: Overview of the project, installation instructions, and usage.
• .github/: GitHub-specific files (e.g., issue templates, workflows).
• .vscode/: VS Code-specific files (formatting rules, Ruff config)
• LICENSE: Software license (GPLv3)

Branching Strategy

Use lowercase alphanumeric characters (a-z, 0-9) in branch names, and separate words with hyphens. The name should describe the work on the branch in a concise and identifiable manner.

• main: Mostly stable code. All feature branches are merged here after testing and sometimes review.
• feature/: Each feature or enhancement gets its own branch (e.g., feature/authentication).
• hotfix/: For urgent bug fixes (e.g., hotfix/login-bug).
• docs/: For updates only affecting the documentation. They do not contain code changes.
• wip/: "work in progress", not expected to be finished soon.

Workflow:

1. Create a new feature or bugfix branch from main.
2. Work on your changes, commit frequently.
3. Push the branch to GitHub.
4. Open a pull request (PR) from your branch to main.
5. After review, the PR will be merged into main.

Dos and Don'ts

1. Don't skip upstream branches when merging.

Caution

Don't merge into main directly if you branched off of other upstream (parent) branches that haven't been merged yet.

Tip

Do merge into parent branch directly, if your changes are dependent on unmerged branches.

Tip

Do branch off of main (or parent of unrelated feature), if your changes unrelated to unmerged branches.

Commit Messages

Follow the Conventional Commits standard:

• feat: A new feature (e.g., feat: add user login).
• fix: A bug fix (e.g., fix: correct API response).
• docs: Documentation changes (e.g., docs: update README).
• style: Code style changes (e.g., style: reformat code).
• refactor: Code refactoring (e.g., refactor: optimize auth middleware).
• test: Adding or modifying tests (e.g., test: add user login tests).

Code Reviews

• Pull Requests: Every change should go through a PR, no direct commits to main.
• Reviewers: At least one reviewer must approve before merging.
• PR Guidelines:
  • Provide a clear description of the changes.
  • Reference related issues or tasks.
  • Mark as draft if work is still in progress.
  • (optional) Include screenshots or GIFs for UI changes.

Testing

• Write unit and integration tests for all new features and bug fixes.
• Run tests locally before pushing code.

Documentation

• Document all new features and updates in the docs/ folder.
• Keep the README.md updated with significant changes.
• Write docstrings/comments in code where necessary for clarity.