Package: battenberg
BattenbergBattenberg is a tool built atop ofCookiecutterto keep Cookiecut projects
in sync with their parent templates. Under the hood, Battenberg relies on Git to manage the merging, diffing, and
conflict resolution story. The first goal of Battenberg is to provide anupgradefeature to Cookiecutter.InstallationWe publishbattenbergtoPyPIfor easy consumption.pipinstallbattenbergIf you're on Mac OS X or Windows please follow theinstallation guidesin thepygit2documentation
as well asbattenbergrelies onlibgit2which needs to be installed first.Please installlibgit2 >= 1.0.If you use SSH to connect togit, please also installlibssh2prior to installinglibgit2!!Most like you can do this viabrew install libssh2if you are on Mac OS X.PrerequistesIt is assumed that your cookiecutter template contains a.cookiecutter.jsonfile at the root directory, or you can override its location by
passing in--context-file. Please use thejsonifyJinja2 extension to dump thecookiecuttertemplate context to.cookiecutter.json.Tip:One problembattenberghas that as divergence between the cookiecutter template and the project itself increase as will the volume of
conflicts needed to be manually resolved for each upgrade merge. To minimize these it is often advisable to fit templates with agenerate_exampleboolean flag which will disable including any example code, instead replacing implementation with apassfor example.UsageInstall aCookiecuttertemplate:battenberg[-O<rootpath>][--verbose]install[--checkoutv1.0.0][--initial-branchmain]<cookiecuttertemplatepath/URL>--checkout- Specifies a target reference (branch, tag or commit) from the cookiecutter template repo, if not specified is it inferred from the default branch for the template repo.-O- Specifies an output folder path, defaults to the current directory.--initial-branch- The default branch for the newly createdgitrepo, if not specified is it inferred from the default branch for the template repo.--verbose- Enables extra debug logging.Upgrade your repository with last version of a template:battenbergupgrade[--checkoutv1.0.0][--no-input][--merge-target<branch,tagorcommit>][--context-file<contextfilename>]--checkout- Specifies a target reference (branch, tag or commit) from the cookiecutter template repo, if not specified is it inferred from the default branch for the template repo.--no-input- Read in the template context from--context-fileinstead of asking thecookiecuttertemplate questions again.--merge-target- Specify where to merge the eventual template updates.--context-file- Specifies where to read in the template context from, defaults to.cookiecutter.json.Note:--merge-targetis useful to set if you are a template owner but each cookiecut repo is owned independently. The value you passto--merge-targetshould be the source branch for a PR that'd targetmainin the cookiecut repo so they can approve any changes.Onboarding existing cookiecutter projectsA great feature ofbattenbergis that it's relatively easy to onboard existing projects you've already cookiecut from an existing template.
To do this you need to follow thebattenberg installinstructions above but use the-Ooutput to specify the directory of the existing
project and it'll create you a newtemplatebranch and attempt to merge just like an upgrade operation.Once you've completed your first merge fromtemplate->mainyou can then follow thebattenberg upgradeinstructions as though it was
generated usingbattenberginitially.High-level designAt a high levelbattenbergattempts to provide a continuous history between the upstream template project and the cookiecut project. It does this by maintaining a disjointtemplatebranch whichbattenbergattempts to keep in sync with the upstream template, it therefore will contain no project-specific changes beyond replacing the template values. Then changes
to thetemplateare incorporated into themainand other branches via agit merge --allow-unrelated-historiescommand for each template update pulled in. This merge commit
should be used to resolve any conflicts between the upstream template and the specialized project.This shows the repo structure immediately after running abattenberg install <template>commandThis shows the repo structure immediately after running abattenberg upgradecommand on the previously installed projectDevelopmentTo get set up run:python3-mvenvenvsourceenv/bin/activate# Install in editable mode so you get the updates propagated.pipinstall-e.# If you want to be able to run tests & linting install via:pipinstall-e".[dev]"Then to actually perform any operations just use thebattenbergcommand which should now be on your$PATH.To run tests:pytestTo run linting:flake8--configflake8.cfgbattenbergReleasing a new version to PyPIReminder to updateHISTORY.mdwith a summary of any updates, especially breaking changes.We utilize GitHub Actions to deploy to PyPI. We've limited it to just publish ongit tags. To release run:# Change to the appropriate commit you want to base the release on.vibattenberg/__init__.py# Update the version string.gittag<version>
gitpushorigin<version>Then watch the build for any errors, eventually it should appear on thebattenbergPyPIproject.FAQI got an error like_pygit2.GitError: unsupported URL protocol, how do I fix this?Likely you're using agitURL withsshand have installedpygit2without access to the underlyinglibssh2library. To test this run:$python-c"import pygit2; print(bool(pygit2.features & pygit2.GIT_FEATURE_SSH))"FalseTo remedy this run:$pipuninstallpygit2
...# Hopefully you have this, but this will install the compiler toolchain for OS X.$xcode-select--install
...
$brewinstalllibssh2
...
$brewinstalllibgit2
...# The python wheels for Mac OS X for pygit2 are not built with SSH support by default so tell pip# to install pygit2 from source.$pipinstallpygit2--no-binarypygit2
...# Finally test out to ensure pygit2 picks up the SSH features.$python-c"import pygit2; print(bool(pygit2.features & pygit2.GIT_FEATURE_SSH))"TrueWhy are you using a new.cookiecutter.jsonpattern instead of using thereplaypattern?Frankly the implementation was quite convoluted to get the intentions of these features to align. With the.cookiecutter.jsonapproach
we're intended for template state to live at the project level instead of at the user level which thereplayfunctionality defaults to.
Overriding that behaviour, whilst possible was convoluted in the currentcookiecutterAPI and would require upstream changes so instead
we decided against trying to align these features.Whybattenberg?A tribute to the shoulders this project stands on,cookiecutter&milhoja, anda tasty cakein its own right.CreditsOriginal codewritten byRaphael Medaerfrom anoriginal
ideaofAbdó Roig-Maranges.LicenseFree software: Apache Software License 2.0Release History0.5.0 (2023-03-31)Update python version to 3.7+0.4.1 (2021-01-25)Suppress stacktrace logging when hook exits unsuccessfully (See#23)Ensure we're compatible with updatedRepository.__init__constructor (See#23)0.4.0 (2020-10-13)Removemasteras the defaultgittarget branch terminology to promote equity and belonging. Instead rely on remote HEAD to infer default branch naming convention.Add in--initial-branchoptional argument tobattenberg installto specify the initial branch to create when initializing a new project.0.3.0 (2020-05-29)Updatepygit2dependency to>= 1.0, can now rely onlibgit2 >= 1.0too. (See#18)Add in better debug logging (See#16)0.2.3 (2020-05-19)Refactor removal of top-level directory after cookiecutting to avoid collisions. (See#15)Set upper limit on pygit2 dependency (See#14)0.2.2 (2020-01-29)Fix regression that stopped injecting context when upgrading.0.2.1 (2020-01-29)Cleans up error message when merging results in conflicts. (See#13)0.2.0 (2019-10-29)Adds in remote fetching oforigin/templatebranch during upgrades. (See#12)0.1.1 (2019-10-17)Revert back to relying on mainlinecookiecutterinstead of Zillow fork. (See#9)0.1.0 (2019-10-10)Add in support for reading template context from.cookiecutter.json. (See#2)Add in--merge-targetCLI option. (See#4)Expanded test coverage, added in CI/CD via Travis CI. (See#8)Prior to v0.1.0battenbergwas developed under themilhojaproject.