Skip to main content
We welcome contributions to Learn Git Branching! This project has a relaxed, friendly environment - there’s no strict formal process.

​
Ways to Contribute

Contributions typically fall into a few categories:

Translations

Add or improve language translations for the application and levels

Bug Fixes

Fix issues, improve browser compatibility, or resolve layout problems

New Features

Add new git commands, improve visualization, or enhance the UI

New Levels

Create educational challenges to teach git concepts

Documentation

Improve code comments, README, or architectural docs

Testing

Add test coverage or improve test infrastructure

​
General Workflow

Follow this standard git workflow when contributing:
1

Fork and clone

Fork the repository on GitHub and clone your fork:
git clone https://github.com/YOUR_USERNAME/learnGitBranching.git
cd learnGitBranching
2

Install dependencies

Set up the development environment:
yarn install
See the setup guide for detailed instructions.
3

Create a feature branch

Create a new branch for your changes:
git checkout -b newAwesomeFeature
Use a descriptive branch name that reflects what you’re working on.
4

Make your changes

Edit source files, write tests, and build frequently:
# Edit files
vim ./src/js/git/index.js

# Fast build to see changes
yarn gulp fastBuild

# Open in browser to test
open ./index.html
See building guide for all build commands.
5

Run tests and linting

Before committing, ensure all tests pass:
yarn gulp build  # Runs tests and linting
Fix any test failures or linting errors.
6

Commit and push

Commit your changes with a clear message:
git add .
git commit -m "Add support for git worktree command"
git push origin newAwesomeFeature
7

Create a pull request

Go to GitHub and create a pull request from your branch to the main repository.

​
Contribution Types

​
Translations

We welcome all translation improvements or additions! How translations work:
  • Levels are stored in giant JSON blobs, keyed by locale for each string
  • The format can be somewhat awkward to edit manually
  • Translations are in src/js/intl/strings.js
Adding a translation:
  1. Open src/js/intl/strings.js
  2. Find the English strings and add corresponding entries for your locale
  3. Test your translation by running the app with your locale
  4. Submit a pull request with your changes
Include screenshots showing your translation in context to help reviewers verify accuracy.

​
Bug Fixes

For general bugs:
  1. Describe the issue and steps to reproduce
  2. Make your fix
  3. Test thoroughly
  4. Submit a pull request with:
    • Description of the bug
    • Your fix approach
    • How you verified the fix
For CSS/layout issues:
  • Attach before and after screenshots
  • Test across multiple browsers if possible
  • For browser-specific issues, use targeted CSS rules by browser
  • Prefer minimal, surgical fixes over broad changes
Use debug_copyTree() in the JS console to capture state before reproducing bugs. This helps maintainers recreate the issue using importTreeNow.

​
New Features

Adding new functionality to the git engine or UI:
1

Discuss first (optional)

For large features, consider opening an issue first to discuss the approach. This can save time if the maintainers have specific preferences.
2

Implement your feature

Make your changes in the appropriate files:
  • Git commands: src/js/git/commands.js
  • Command parsing: src/js/commands/index.js
  • GitEngine core: src/js/git/index.js
  • UI components: src/js/react_views/ or src/js/views/
3

Add tests

If adding new functionality to the git engine, add tests in __tests__/:
// Example test
it('should handle git worktree command', function() {
  var main = new Main();
  main.runCommand('git worktree add ../feature');
  // Assert expected behavior
});
Tests should cover:
  • Normal operation
  • Edge cases
  • Error conditions
4

Document your changes

Add inline code comments for complex logic. Update README.md if adding user-facing features.

​
Creating New Levels

You can create educational levels using the built-in level builder:
1

Launch the level builder

In the application, run:
build level
A dialog will walk you through:
  • Setting up the starting commit tree
  • Writing the goal description
  • Defining the target state
  • Adding hints (optional)
2

Test your level

Play through your level to ensure:
  • Instructions are clear
  • The goal is achievable
  • The solution validation works correctly
  • Difficulty is appropriate for the sequence
3

Share your level

At the end of the builder process, you’ll get a JSON blob. You can:
  • Paste it in a GitHub Gist and share the URL
  • Open an issue with the JSON and we can review/merge it
  • Share directly with friends using import level command
  • Submit a PR by creating a new file in src/levels/
Custom level URL example: 
https://pcottle.github.io/learnGitBranching/?gist_level_id=a84407351f9c9f0cb241

​
Pull Request Guidelines

  • Clear description of what your PR does
  • Why the change is needed
  • Any relevant issue numbers
  • Screenshots for UI changes
  • Test results (if applicable)
  • Follow the existing code style
  • Run JSHint to catch common issues: gulp jshint
  • Use meaningful variable names
  • Add comments for non-obvious logic
For git engine changes:
  • Add tests in __tests__/ folder
  • Tests should be simple: input commands, check expected tree state
  • All existing tests must pass: yarn test
For UI changes:
  • Manual testing is usually sufficient
  • Include screenshots showing the change
  • Maintainers will review your PR when available
  • Be responsive to feedback and questions
  • Make requested changes in new commits (don’t force push)
  • Once approved, your PR will be merged

​
Reporting Issues

When reporting bugs or issues:
1

Check existing issues

Search the issue tracker to see if your issue has already been reported.
2

Provide detailed information

Include:
  • Clear description of the issue
  • Steps to reproduce
  • Expected vs actual behavior
  • Browser and OS information
  • Screenshots or GIFs if relevant
3

Use debug tools

Run debug_copyTree() in your JS console when in the state that reproduces the bug. Paste the output in your issue report.This allows maintainers to use importTreeNow to recreate your exact state.

​
Development Tips

​
Quick Iteration

For fast development cycles: 
# Use fast build
yarn gulp fastBuild

# Or use watch mode
yarn gulp watching

# Or use dev server
yarn dev

​
Running Tests

# All tests
yarn test

# Single test file
npx gulp-jasmine __tests__/git.spec.js

# With coverage
yarn test:coverage

​
Browser Testing

After building, simply open index.html: 
# macOS
open index.html

# Linux  
xdg-open index.html

# Windows
start index.html

​
Debugging

Use browser developer tools:
  • Console: Run debug_copyTree() to export state
  • Network: Check if assets are loading
  • Sources: Set breakpoints in source files
  • Elements: Inspect SVG visualization elements

​
Questions or Need Help?

GitHub Issues

Ask questions or report issues

Pull Requests

View open pull requests for examples
Don’t hesitate to ask questions in issues or pull requests. The maintainers and community are friendly and happy to help!

​
Recognition

All contributors are recognized in the README with their GitHub avatars. Your contributions, no matter how small, are valued and appreciated. Thank you for contributing to Learn Git Branching!

Build docs developers (and LLMs) love

Get started for freeTalk to us