Skip to main content

Git Methodology

Overview​

The Virtual Rodent project uses Git for version control and Gitea as the team's hosted Git platform. The team follows the GitHub Flow development methodology, adapted to the project's Gitea environment.

The purpose of this workflow is to keep the main branch stable while allowing team members to work independently on individual features.

GitHub Flow​

The team's workflow follows a simple feature-based development cycle:

Main Branch
    ↓
Create Feature Branch
    ↓
Develop Feature
    ↓
Commit Changes
    ↓
Push Feature Branch
    ↓
Create Pull Request
    ↓
Review / Test
    ↓
Merge into Main

The main branch represents the integrated version of the project. New functionality should be developed in separate feature branches rather than directly on main.

Feature Branches​

Each feature or task should have its own branch.

Team members must not use one personal branch for all of their work. For example, a branch named after a team member such as ahmed should not contain multiple unrelated features.

Instead, a new branch should be created for every feature:

feature/stimuli-recording
feature/treatment-system
feature/arena-collision
feature/ui-controls
feature/data-export

This keeps changes isolated and makes it easier to review, test, merge, and revert individual features.

Branch Naming​

Branches should use descriptive names that clearly communicate the purpose of the work.

The preferred convention is:

feature/<feature-name>

Examples:

feature/stimuli-recording
feature/experiment-presets
feature/trajectory-recording
feature/ui-controls

Bug fixes can use:

fix/<issue-name>

For example:

fix/stimulus-activation

Branch names should describe the work being performed rather than the name of the person working on it.

Development Workflow​

Before beginning a new feature, the developer should ensure their local main branch is up to date.

A typical workflow is:

git checkout main
git pull
git checkout -b feature/<feature-name>

The feature is then implemented and tested on the feature branch.

Changes are committed regularly using clear commit messages:

git add .
git commit -m "Add stimulus recording"

The feature branch is then pushed to Gitea:

git push -u origin feature/<feature-name>

Pull Requests and Merging​

Once a feature is complete and its tests pass, a pull request is opened from the feature branch into main.

The pull request allows the team to:

  • Review the implementation
  • Discuss changes
  • Check that requirements have been met
  • Verify that tests pass
  • Identify potential problems before integration

After review and approval, the feature branch can be merged into main.

The main branch should therefore contain integrated and reviewed functionality rather than incomplete feature development.

Keeping Branches Focused​

A feature branch should contain changes related to one logical feature.

For example, if a developer is implementing stimulus recording, the branch should focus on:

feature/stimuli-recording

It should not also contain unrelated changes to the user interface, arena physics, or documentation unless those changes are required for the feature.

This makes pull requests smaller and easier for other team members to understand.

Pulling and Updating Work​

When starting new work, developers should update their local main branch before creating a new feature branch.

If main has changed while a feature is being developed, the developer should update their branch as appropriate before creating the pull request. This helps identify integration conflicts before the feature is merged.

Commit Messages​

Commit messages should briefly describe the change being introduced.

Examples include:

Add stimulus recording
Fix deterministic simulation test
Add treatment event recording
Implement experiment preset loading
Add arena boundary collision

Commits should represent meaningful changes rather than unrelated collections of modifications.

Why GitHub Flow Was Selected​

GitHub Flow was selected because it provides a simple workflow suitable for a small development team working on a continuously evolving software project.

Its feature-branch approach provides:

  • Isolation between features
  • Easier code review
  • Reduced risk to the main branch
  • Clear contribution history
  • Easier debugging and rollback
  • A straightforward workflow for team members

Although the workflow is called GitHub Flow, the methodology is platform-independent. The team uses the same principles while hosting the repository on Gitea.

Contribution Traceability​

Because each feature is developed in its own branch and merged through a pull request, individual contributions can be traced through the Git history.

This provides evidence of:

  • Which team member implemented a feature
  • Which changes were made
  • When the changes were made
  • Which feature the changes belonged to
  • How the feature was integrated into the main project

This Git history complements the project's Work Tracker and provides an additional record of team contributions.

AI Attribution: The preceding document was generated and edited with assistance from ChatGPT Web (GPT-5.6 Luna).