5. Core Committer Guide¶
5.1. Vision and Scope¶
Core committers, use this section to:
- Guide your instinct and decisions as a core committer
- Limit the codebase from growing infinitely
5.1.1. Command-Line Accessible¶
- Provides a command-line utility that creates projects from cookiecutters
- Extremely easy to use without having to think too hard
- Flexible for more complex use via optional arguments
5.1.2. API Accessible¶
- Entirely function-based and stateless (Class-free by intentional design)
- Usable in pieces for developers of template generation tools
5.1.3. Being Jinja2-specific¶
- Sets a standard baseline for project template creators, facilitating reuse
- Minimizes the learning curve for those who already use Flask or Django
- Minimizes scope of Cookiecutter codebase
Being extendable by people with different ideas for Jinja2-based project template tools.
- Entirely function-based
- Aim for statelessness
- Lets anyone write more opinionated tools
Freedom for Cookiecutter users to build and extend.
- No officially-maintained cookiecutter templates, only ones by individuals
- Commercial project-friendly licensing, allowing for private cookiecutters and private Cookiecutter-based tools
5.1.5. Fast and Focused¶
Cookiecutter is designed to do one thing, and do that one thing very well.
- Cover the use cases that the core committers need, and as little as possible beyond that :)
- Generates project templates from the command-line or API, nothing more
- Minimize internal line of code (LOC) count
- Ultra-fast project generation for high performance downstream tools
- Cross-platform and cross-version support are more important than features/functionality
- Fixing Windows bugs even if it’s a pain, to allow for use by more beginner coders
- Aim for 100% test coverage and covering corner cases
- No pull requests will be accepted that drop test coverage on any platform, including Windows
- Conservative decisions patterned after CPython’s conservative decisions with stability in mind
- Stable APIs that tool builders can rely on
- New features require a +1 from 3 core committers
5.1.8. VCS-Hosted Templates¶
Cookiecutter project templates are intentionally hosted VCS repos as-is.
- They are easily forkable
- It’s easy for users to browse forks and files
- They are searchable via standard Github/Bitbucket/other search interface
- Minimizes the need for packaging-related cruft files
- Easy to create a public project template and host it for free
- Easy to collaborate
5.2. Process: Pull Requests¶
If a pull request is untriaged:
- Look at the roadmap
- Set it for the milestone where it makes the most sense
- Add it to the roadmap
How to prioritize pull requests, from most to least important:
- Fixes for broken tests. Broken means broken on any supported platform or Python version.
- Extra tests to cover corner cases.
- Minor edits to docs.
- Bug fixes.
- Major edits to docs.
Ensure that each pull request meets all requirements in this checklist: https://gist.github.com/audreyr/4feef90445b9680475f2
5.3. Process: Issues¶
If an issue is a bug that needs an urgent fix, mark it for the next patch release. Then either fix it or mark as please-help.
For other issues: encourage friendly discussion, moderate debate, offer your thoughts.
New features require a +1 from 2 other core committers (besides yourself).
5.4. Process: Roadmap¶
Due dates are flexible. Core committers can change them as needed. Note that GitHub sort on them is buggy.
How to number milestones:
- Follow semantic versioning. See http://semver.org
- If a milestone contains too much, move some to the next milestone.
- Err on the side of more frequent patch releases.
5.5. Process: Pull Request merging and HISTORY.rst maintenance¶
If you merge a pull request, you’re responsible for updating AUTHORS.rst and HISTORY.rst
When you’re processing the first change after a release, create boilerplate following the existing pattern:
x.y.z (Development) ~~~~~~~~~~~~~~~~~~~ The goals of this release are TODO: release summary of features Features: * Feature description, thanks to @contributor (#PR). Bug Fixes: * Bug fix description, thanks to @contributor (#PR). Other changes: * Description of the change, thanks to @contributor (#PR). .. _`@contributor`: https://github.com/contributor
5.6. Process: Accepting Template Pull Requests¶
- Run the template to generate the project.
- Attempt to start/use the rendered project.
- Merge the template in.
- Update the history file.
Adding a template doesn’t give authors credit.
5.7. Process: Generating CONTRIBUTING.rst¶
From the cookiecutter project root:
$ make contributing
This will generate the following message:
rm CONTRIBUTING.rst touch CONTRIBUTING.rst cat docs/contributing.rst >> CONTRIBUTING.rst echo "\n\n" >> CONTRIBUTING.rst cat docs/types_of_contributions.rst >> CONTRIBUTING.rst echo "\n\n" >> CONTRIBUTING.rst cat docs/contributor_setup.rst >> CONTRIBUTING.rst echo "\n\n" >> CONTRIBUTING.rst cat docs/contributor_guidelines.rst >> CONTRIBUTING.rst echo "\n\n" >> CONTRIBUTING.rst cat docs/contributor_testing.rst >> CONTRIBUTING.rst echo "\n\n" >> CONTRIBUTING.rst cat docs/core_committer_guide.rst >> CONTRIBUTING.rst echo "\n\nAutogenerated from the docs via \`make contributing\`" >> CONTRIBUTING.rst echo "WARNING: Don't forget to replace any :ref: statements with literal names" WARNING: Don't forget to replace any :ref: statements with literal names
5.8. Process: Your own code changes¶
All code changes, regardless of who does them, need to be reviewed and merged by someone else. This rule applies to all the core committers.
- Minor corrections and fixes to pull requests submitted by others.
- While making a formal release, the release manager can make necessary, appropriate changes.
- Small documentation changes that reinforce existing subject matter. Most commonly being, but not limited to spelling and grammar corrections.
- Ensure cross-platform compatibility for every change that’s accepted. Windows, Mac, Debian & Ubuntu Linux.
- Ensure that code that goes into core meets all requirements in this checklist: https://gist.github.com/audreyr/4feef90445b9680475f2
- Create issues for any major changes and enhancements that you wish to make. Discuss things transparently and get community feedback.
- Don’t add any classes to the codebase unless absolutely needed. Err on the side of using functions.
- Keep feature versions as small as possible, preferably one new feature per version.
- Be welcoming to newcomers and encourage diverse new contributors from all backgrounds. See the Python Community Code of Conduct (https://www.python.org/psf/codeofconduct/).
5.10. Becoming a Core Committer¶
Contributors may be given core commit privileges. Preference will be given to those with:
- Past contributions to Cookiecutter and other open-source projects. Contributions to Cookiecutter include both code (both accepted and pending) and friendly participation in the issue tracker. Quantity and quality are considered.
- A coding style that the other core committers find simple, minimal, and clean.
- Access to resources for cross-platform development and testing.
- Time to devote to the project regularly.