Conventions relating to github management
This document outlines the conventions for GitHub management, including:
Naming and Messages
Repositories
- Repository names should use kebab-case, which consists of all lowercase letters and dashes. For example,
name-of-repo
. Refer to Kebab case for more details. - Repositories should be tagged with appropriate topics in the about section (e.g., python, docker-compose, react, etc.). These topics can be used to filter repositories.
- Releases should use git tags and conform to Semantic Versioning, using the format
major.minor.patch
without a ‘v’ prefix. - Each repository should include a LICENSE file. For source code, use the MIT license. For datasets, use the CC-BY license.
Specific rules for naming
Application | Example | Regex Rule |
---|---|---|
Python packages | py-sema | ^py-[a-z0-9\-]+$ |
GitHub Actions | rohub-sync-action | ^[a-z0-9\-]+-action$ |
GitHub Pages Actions | space-to-pages | ^[a-z0-9\-]+-pages$ |
RO-Crates | observatory-bpns-crate | ^[a-z0-9\-]+-crate$ |
Web components | rocrate-preview-widget | ^[a-z0-9\-]+-widget$ |
Branches
Each repository should have two default branches:
main
: For release-ready code.gh-pages
: For documentation. This branch is automatically maintained by a documentation workflow.
Additional branches should be created for each change. The branch name should reflect the change, using the format {category}/{description}
. For example, fix/connection_bug
. The description should be a short summary of the change, using snake case
The category should be one of the following:
- fix
- feature
- refactor
- chore
- docs
- (add more if needed)
Commits
Commit messages should follow the Conventional Commits specification. The commit message should follow this format:
"<type>: {action} {what} {where} {why} "
ex: refactor: change args in funcA to allow tipehinting
The allowed types are:
- build
- chore
- ci
- docs
- feat
- fix
- perf
- refactor
- revert
- style
- test
The Conventional Commits specification allows for additional information in the body and footer of the commit message.
Rules
Pull Request
Every code change should be made on a new branch and submitted as a pull request (PR). Direct pushes to the main
branch are not allowed.
When opening a PR, provide a descriptive name (which can be similar to the branch name) and a description explaining the purpose of the PR. Use GitHub keywords if applicable.
Before a PR can be merged, it must:
- Receive at least one approval.
- Pass all checks, including:
- Linting
- Testing
- Test Coverage
The commits within the PR should tell a cohesive story. Each commit should be clear, concise, and focused on a single change.