Modularise - Demo project
This repository contains a piece of a demo setup for the modularise tool. The proposal and technical design document for this tool can be found here.
Project layout
The project implements a placeholder command-line implementation. The command-line is capable of printing random numbers and strings based on being passed either "number" or "string as argument. An evolution of the tool also supports passing a second length argument in the case of a first "string" parameter.
The project's implementation is spread across four separate packages:
- The
main
package that implements the CLI. - The
numberutils
package that exposes the functionality of printing a random number. - The
stringutils
package that exposes the functionality of printing a random string. - The
random
package that exposes the generation of random numbers and strings.
For the demonstration's purposes all packages should be considered as implementing related but standalone APIs. The overall project's end-product is the CLI tool itself but downstream users may also depend on the underlying implementation APIs to satisfy advanced use-cases.
Repository layout
- The "core" repository can be found at Helcaraxan/modularise-example-core. It contains four
separate branches:
- A
master
branch that contains an initial version of the CLI tool. - A
master-extension
branch that contains the CLI tool with the length argument added to string printing. - A
modularised
branch that contains a "modularised" version ofmaster
. - A
modularised-extension
branch that contains a "modularised" version ofmaster-extension
.
- A
- The "numberutils" split can be found at Helcaraxan/modularise-example-numberutils. It contains
the extracted source code of the
numberutils
project of the "core" repository. To satisfy its dependencies it also contains a copy of therandom
package in itsinternal/
subtree. It contains one branch:- A
master
branch that contains the extracted code of thenumberutils
package from the "core" repository'smodularised
branch.
- A
- The "stringutils" split can be found at Helcaraxan/modularise-example-stringutils. It contains
the extracted source code of the
stringutils
project of the "core" repository. To satisfy its dependencies it also contains a copy of therandom
package in itsinternal/
subtree. It contains two branches:- A
master
branch that contains the extracted code of thestringutils
package from the "core" repository'smodularised
branch. - A
master-v2
branch that contains the extracted code of thestringutils
package from the "core" repository'smodularised-extension
branch.
- A
Walk-through of the modularise tool usage
The master
and master-extension
branches in the "core" repository represent the evolution of
the project without the use of the modularise tool. Adding the ability to specify a string length
is a non-breaking change from the CLI perspective and, if a new release were to be tagged, it would
be considered a new minor version of the project's system-level API. However from a Go module
perspective it should be a major release given that there has been a breaking change in the
stringutils
API.
In the case of the "modularised" project, the numberutils
and stringutils
, as well as the
random
implementation-level APIs have been moved to an internal/
subtree. The numberutils
and
stringutils
are both mirrored in the split repositories.
As a result:
- The
modularised-extension
branch could be released as a "proper" new module minor version of the project, contrary to themaster-extension
branch, because there is no breaking change in the core repository's public API. - The
modularised-extension
branch corresponds, like themodularised
branch, to the HEAD commit on themaster
branch in the numberutils repository because there are no changes to thenumberutils
package in the core repository. - The
modularised-extension
branch corresponds to the HEAD commit of themaster-v2
branch in the stringutils repository, unlike themodularised
branch which maps to the HEAD commit of the repository'smaster
branch. Themaster-v2
branch will be released as a new major version of the split because of the breaking change to its public API.
Summary of the branch mappings between the core and split repositories:
core | numberutils | stringutils |
---|---|---|
master |
N.A | N.A |
master-extension |
N.A | N.A |
modularised |
master |
master |
modularised-extension |
master |
master-v2 |