Cranko provides a special
command to help you start using Cranko with a preexisting repository.
Ideally, to bootstrap a repository to use Cranko all you need to do is enter its working tree and run:
$ cranko bootstrap
Go ahead and try it! It will try to print out detailed information about what it’s doing. Since you must run the program in a Git repository working tree, if it does anything that you don’t like you can always reset your working tree to throw away the tool’s changes.
Hopefully the tool won’t crash, but these are early days and everyone’s repo is unique. If you have problem not addressed in the text below, file an issue.
Cranko needs to know the identity of your upstream repository, which is defined
as the one that will perform automated release processing upon updates to its
rc-like branch. The bootstrapper will begin by attempting to guess the
identity of upstream by looking for a Git remote named
origin, or choosing the
only remote if there is only one. If this guessing process fails, use the
--upstream option to specify the name of the upstream explicitly.
The bootstrapper will save the URL of the upstream remote into the main Cranko
may want to add additional likely upstream URLs to this configuration file
(e.g., both HTTPS and SSH GitHub remote URLs). Cranko identifies the upstream
from its URL, not its Git remote name, since Git remote names can vary
arbitrarily from one checkout to the next.
The bootstrapper will search for recognized projects in the repo and print out a summary of what it finds.
NOTE: The goal is for Cranko to recognize all sorts of projects, but currently it knows a modest group of them: Rust/Cargo, NPM, and Python. If you’re giving Cranko a first try this is the limitation that is most likely to be a dealbreaker. Please file an issue reporting your needs so we know what to prioritize.
ALSO: There is a further goal that one day you’ll be able to manually configure projects that aren’t discovered in the autodetection phase, but that functionality is also not yet implemented.
As per the just-in-time versioning workflow, on the main development
branch of your repository, the version numbers of all projects should be set to
some default “development” value (e.g.
0.0.0-dev.0) that is never planned to
change. Cranko will rewrite all of the metadata files that it recognizes to
perform this zeroing.
But you’re presumably not going to want to actually reset the versioning of
all your projects. The current version numbers will be preserved in a “bootstrap”
configuration file (
.config/cranko/bootstrap.toml) that Cranko will use as a
basis for assigning new version numbers.
If your repository contains more than one project, some of those projects
probably depend on each other. With zeroed-out version numbers, it is not
generally possible to express the version constraints of those internal
dependencies in existing metadata formats. For instance, before bootstrapping,
you might have had a package
foo_cli that depends on
foo_lib >= 1.3: it
works if linked against
foo_lib version 1.3.0, but not if linked against
foo_lib version 1.2.17. That didn’t stop being true just because the version
numbers in on your main development branch got zeroed out!
The boostrapping process transfers your preexisting internal dependency version requirements into extra Cranko metadata fields so that they will be correctly reproduced in new releases. Once you start making releases that depend on newer versions of your projects, it is recommended that you transition these “manually” coded version requirements to Cranko-native ones based in Git commit identifiers (as motivated in the just-in-time versioning section).
Once the bootstrapper has run, you should review the changes it has made, see if they make sense, and try building the code in your repo. You may need to modify your build scripts depending on what expectations they have about the version numbers assigned in your main development branch.
After you are happy with Cranko’s changes, commit them, making sure to add the
new files in
The next step is to modify your CI/CD system to start using the
cranko release-workflow commands to start implementing the just-in-time
versioning model — see the CI/CD Workflows section for
documentation on what to do. This phase generally takes some trial-and-error,
but in most cases you should only need to insert a few extra commands into your
CI/CD scripts at first. Generally, it is easiest to start by updating the
processes that run on updates to the main development branch (e.g.
on pull requests. If you do this work on a branch other than your main
development branch, make sure that your Cranko-ified CI/CD scripts will run on
updates to that branch.
As you work on the CI/CD configuration for main development work, you probably
won’t actually need to use any of the Cranko commands described in the Everyday
Development section. But once your basic processing is working, you
should start using those commands to simulate releases and work on setting up
the CI/CD workflows that run on updates to the new
rc branch that you will be
creating — these are the workflows that will actually run the automated release
machinery if/when your builds succeed. If you haven’t been using release
automation before, it can take some patience to set everything up properly. But,
we hope that you still soon start feeling the warm fuzzies that arise when these
usually annoying tasks start Just Working!