This repository follows an issue-driven development workflow with staged environments to avoid conflicts and ensure code quality, traceability, and collaboration.
Please review this guide in its entirety before making a contribution.
- Development Process
- Branching Strategy
- Issue Workflow
- Commit Message Guidelines
- Pull Request Process
- Code Standards
- Testing Requirements
- Review & Merge Policy
| Step | Action |
|---|---|
| 1.1 | Get necessary contribution permissions from Dr. Udell |
| 1.2 | Communicate with the team about the feature you plan to implement (see communication guidelines in Standard Operating Procedures SOP file) |
| 1.3 | See README.md for setup instructions and environment configuration. |
| Step | Action |
|---|---|
| 2.1 | Select or create an Issue, following the Issue Workflow |
| 2.2 | Assign yourself as the Issue owner |
| 2.3 | Create a feature branch from dev (see Branching Strategy) |
| 2.4 | Make frequent pull requests (during each work cycle) to avoid merge conflicts |
| 2.5 | Document your code with detailed comments so that other contributors can understand the logic behind your implementation |
| 2.6 | Commit changes in small logical parts, following the Commit Message Guidelines |
| 2.7 | Finally, submit a pull request to the dev branch only, following the Pull Request Process (features can only be pushed to main after Dr. Udell's approval) |
⚠️ Each Pull Request must reference an Issue
⚠️ Feature branches should not be active for more than 2-3 days to avoid merge conflicts
| Step | Action |
|---|---|
| 3.1 | Follow the Testing Requirements and Merge Policies before attempting a merge |
| 3.2 | Communicate with the team once the PR has been approved so the dev site may be tested and approval can be given for a PR to main |
| 3.3 | Once the dev site has been tested and approved by Dr. Chet, create a new PR to main and await merge approval |
| Step | Action |
|---|---|
| 4.1 | Once feature branches have been sucessfuly merged to main (after dev tesitng and approval), feature branches can be safely deleted as per indusry standards (merge and PR history, as well as project/file version history will remain accessible after feature branch deletions) |
Note: Branches can only be restored if associated with a PR and can be accessed through the PR's history/overview
This project uses a staged branching model:
-
main- Main branch
- Protected (no direct commits) - PRs to main must be approved by Dr. Udell
- All merges or changes to
mainwill reflect on Ear2Earth's live main website - Represents the live application
-
dev- Integration and testing branch
- All feature work is merged here first
- All merges or changes to
devwill reflect on Ear2Earth's live dev website
-
feature/*- Used for all development work
- Must be created from
dev
Examples:
feature/packet-refesh-buttonfeature/error-handlingfeature/improved-load-time
All work must be tracked using GitHub Issues.
- New features
- Bug fixes
- Design improvements
- Performance improvements
- Infrastructure or CI changes
- Testing
| Bug Fixes, Infrastructure, and Testing | New Features and Design/Performance Improvements |
|---|---|
| Each issue should include: | Each issue should include: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Issues serve as the source of truth for all work.
You can close an issue by linking it to a Pull Request. Use GitHub’s supported keywords in your PR description:
- Keywords: Closes #123, Fixes #123, or Resolves #123
- This automatically closes the issue once the PR is merged and creates a permanent link between the fix and the issue
If you are closing an issue manually (without a PR), please provide a final comment that includes:
- Summary: A brief explanation of the resolution
- Reference: Links to any relevant commits, external documentation, or related discussions
- Reasoning: If closing as "Won't Fix" or "Duplicate," clearly state the reason
If an issue has no activity for more than six months, it will be labeled as 'stale' or will be closed as "Unplanned".
If you would like to create a new issue but there is a an older, less descriptive version:
- Create an improved, more descriptive issue
- Navigate to the older issue and choose 'Close as duplicate'
- Choose your new issue from the dropdown as the replacement issue
Commit messages should be clear and descriptive.
Examples:
Change timezone from local to UTCFix button hover functionalityImplement testing for mulitple sound types
Avoid vague messages such as:
fixchangeswip
All changes must be submitted via Pull Request.
- Reference the related Issue (e.g.,
Closes #42) - Clearly describe:
- What was changed
- Why the change was needed
- How the change was implemented
- Include testing steps or screenshots if applicable
Each PR should have:
- One primary contributor
- Optional co-contributors noted in the description
Note: This is a key factor in your resume-aware worflow, as PR's give you a chance to show off your skills to future employers. Keep things concise but descriptive in your contribution reasoning and documentation.
- Follow existing project structure and conventions
- Keep changes focused and scoped to the Issue
- Avoid unrelated refactors in the same PR
- Use consistent naming and formatting
Linting and formatting tools must pass before merging.
- All existing tests must pass
- New features should include tests when applicable
- Manual testing steps should be documented in the PR
No PR will be merged if it breaks existing functionality.
- All PRs require at least one reviewer approval
- CI checks must pass
- No direct commits to
mainordev devis merged intomainonly after validation
For questions related to workflow or contribution guidelines, refer to the team SOP file or contact the project maintainers.
Thank you for contributing to Ear2Earth!