Skip to main content

GitHub Workflow

Overview​

This document describes how to effectively collaborate on the pyicub project using GitHub. Our team uses a trunk-based development approach. This means that all work is centered around a single primary branch: master. All new code is merged into this branch through short-lived, goal-oriented branches.

This document is written to help developers understand how to contribute safely and effectively.

Branching Strategy​

We use a simple and scalable branching strategy:

Branch NameProtected?Base BranchDescription
masterYESN/AThe main production branch. All stable code lives here.
feature/*NOmasterShort-lived branches for new features. Merged into master when ready.
bugfix/*NOmasterShort-lived branches for small fixes. Merged into master.
v1.xYESmasterLong-term release branches for major or divergent versions of the library.

Key Points:​

  • master is the trunk: All production-ready code goes here.
  • feature/* branches are created to develop isolated features. They are merged into master once completed and reviewed.
  • bugfix/* branches are used for fixing specific bugs and are merged into master with the corresponding version bump (usually PATCH).
  • vX.Y branches are created when major changes require a divergence (e.g., a move from icubSim to gazebo). These branches are independently maintained and versioned.

Typical Development Workflow​

  1. Start from master

    git checkout master
    git pull origin master

  2. Create your feature or bugfix branch

    git checkout -b feature/my-new-feature

  3. Make your changes locally

  4. Commit regularly with meaningful messages

    git commit -m "feat: add new grasp controller"

    We encourage using Conventional Commits where possible:

    • feat: for new features
    • fix: for bug fixes
    • docs: for documentation
    • refactor: for internal refactoring without behavior change

  5. Push your branch and open a pull request (PR)

    git push origin feature/my-new-feature
    • Open the PR from GitHub.
    • Clearly describe what the PR does.
    • Link to any related issues.
    • Assign reviewers.

  6. Get the code reviewed and approved

    • Every Pull Request must be reviewed by at least one team member.
    • Ensure all tests pass (local and CI checks).

  7. Merge into master

    • Once approved and tested, merge the PR into master.

Hotfixes​

If an urgent bug is discovered in production:

  1. Create a bugfix branch from master:

    git checkout master
    git pull origin master
    git checkout -b bugfix/fix-title-error

  2. Apply and commit the fix, then merge into master.

  3. Bump the PATCH version and tag the release.

    For how to tag releases and version properly, refer to the Tagging Releases section in Releases.md.

  4. If the bug also affects an older version (e.g., v0.3), cherry-pick the fix into that version branch.

Versioning and Tags​

Our project follows Semantic Versioning with practical adaptations during early development (v0.x.y). For guidance on when to bump versions and how to tag them correctly, refer to the Versioning Strategy and Tagging Releases sections in Releases.md.

Best Practices​

  • One task per branch: keep changes isolated and easy to review.
  • Use clear, descriptive branch and commit names.
  • Never push to master directly — always use PRs.
  • Keep branches up to date with master to avoid conflicts.
  • Delete merged branches to keep the repository clean.