Contribution Standards
Contributions need to meet the bar for inclusion in git.git. Although filter-repo is not part of the git.git repository, we want to leave the option open for it to be merged in the future. As such, any contributions need to follow the same guidelines for contribution to git.git, with a few exceptions noted below.How to Submit Changes
For Small Changes
For very short single-commit changes, feel free to open GitHub Pull Requests.For Larger Changes
For more involved changes:- Prefer using
git format-patchandgit send-emailwhen possible - If format-patch or send-email give you too much trouble, go ahead and open a GitHub PR and mention that email didn’t work out
If Emailing Patches
If you choose to email patches to the git list:-
Include “filter-repo” at the start of the subject:
Instead of just:
- CC the maintainer instead of the git maintainer
While GitHub PRs are not the preferred method for the git project, git-format-patch and git-send-email can be challenging. We accept PRs to make contributing easier, especially for newcomers.
Coding Guidelines
Python Version Requirements
- Python 3 is required - Python 2 reached EOL at the end of 2019 and is not supported
- You can depend on anything in Python 3.6 or earlier
- This minimum version may be bumped over time, but generally aims to work with the Python 3 version found in current enterprise Linux distributions
Python Style Guidelines
Git’s CodingGuidelines for python code are only partially applicable:Bytestrings vs Unicode Strings
Using unicode strings result in lots of ugly errors since input comes from:- Filesystem names
- Commit messages
- File contents
- None of which are guaranteed to be unicode
Code Formatting
- Use two-space indents for consistency with the existing codebase
- Otherwise, generally follow PEP 8
Testing Requirements
If you add or modify code, please test line coverage:- Run the testsuite under coverage3 (which you’ll need to install)
- Report on line coverage
- Line coverage of contrib and test scripts can be ignored
- Only git-filter-repo itself must maintain 100% coverage
Code Review Process
Don’t Be Intimidated by Detailed Feedback
In the git community, thorough reviews are standard practice:- Even experienced contributors receive detailed feedback
- It’s common to spend as much or more time fixing up patches after submitting them as creating the initial version
- This process is valuable for learning and maintaining code quality
- The goal is to make contributions acceptable for git.git itself
What Makes a Good Contribution
Well-Tested Code
- All code paths should be tested
- Edge cases should be covered
- Tests should be clear and maintainable
Clear Documentation
- Update relevant documentation for your changes
- Include examples where appropriate
- Explain the “why” not just the “what”
Following Conventions
- Match the existing code style
- Use consistent naming
- Follow established patterns in the codebase
Areas for Contribution
Some ways you can contribute:- Bug fixes - Fix issues reported by users
- Performance improvements - Make filtering faster
- Documentation - Improve clarity and add examples
- Test coverage - Add tests for edge cases
- New features - Add capabilities that fit the tool’s design philosophy
- Example scripts - Create helpful filter-repo demos
Getting Started
- Fork the repository on GitHub
- Clone your fork locally
- Create a branch for your changes
- Make your changes following the guidelines above
- Test thoroughly including running
make test - Submit via PR or email as appropriate
Questions?
If you have questions about contributing:- Review the FAQ
- Check existing GitHub issues
- Look at previous contributions for examples
- Open a discussion issue to ask questions before starting major work