|
| 1 | +# The mental model used by bump-my-version |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +There are four main concepts in bump-my-version: |
| 6 | + |
| 7 | +1. Configuration |
| 8 | +2. Version handling |
| 9 | +3. File changing |
| 10 | +4. Source control management interface |
| 11 | + |
| 12 | +## Configuration |
| 13 | + |
| 14 | +The predecessor to bump-my-version, [bumpversion](https://github.com/peritus/bumpversion), was designed to have the configuration file optional. All configuration values could be specified on the command line. This only worked in the simplest of version schemes. |
| 15 | + |
| 16 | +bump-my-version is designed to have a configuration file. The configuration file is required to specify the version scheme. The configuration file is also used to specify the files to change and how to change them. |
| 17 | + |
| 18 | +## Version handling |
| 19 | + |
| 20 | +bump-my-version abstracts the version handling into a few concepts: |
| 21 | + |
| 22 | +A **version spec** defines all the possible _version component specs_ of a version and how they work together. |
| 23 | + |
| 24 | +A **version component spec** defines how a single part of a _version spec,_ such as `major`, `minor`, or `patch`, works. It defines the types of values, how to increment the component, and how to reset it. |
| 25 | + |
| 26 | +A **version parser** is a regular expression used in several ways. It's named capture groups define the possible components in a version spec and the order in which they appear. It is also used to parse a version string into a mapping of version component name to value. |
| 27 | + |
| 28 | +A **version** is the concrete representation of a _version spec._ It is a mapping of version component names to _version components._ |
| 29 | + |
| 30 | +A **version component** is the concrete representation of a _version component spec._ It is a _version component spec_ with a specific value. |
| 31 | + |
| 32 | +A **version serialization format** is a list of format strings used to serialize a _version_ into a string. |
| 33 | + |
| 34 | +### How a version spec is generated |
| 35 | + |
| 36 | +:::{figure-md} fig-version-spec |
| 37 | + |
| 38 | + |
| 39 | +How a configuration file is used to generate a version spec. |
| 40 | +::: |
| 41 | + |
| 42 | +The most important part of the configuration file is the _version parser._ It defines the structure of the _version spec._ |
| 43 | + |
| 44 | + |
| 45 | +If the configuration file contains a _version component spec_ that matches a named capture group in the _version parser,_ then that _version component spec_ is used in the _version spec._ The yellow and green named capture groups in the diagram demonstrate this. |
| 46 | + |
| 47 | +If the configuration file does not contain a _version component spec_ that matches a named capture group in the _version parser,_ then a default _version component spec_ is used. The blue named capture group in the diagram demonstrates this. |
| 48 | + |
| 49 | +The _component dependency_ graph is used to determine the order in which the _version components_ are incremented and reset. For example in the diagram, the `patch` component depends on the `minor` component which depends on the `major` component. Therefore, when the `major` component is incremented, the `minor` component is reset, which cascades to the `patch` component. |
| 50 | + |
| 51 | +### How a version is generated |
| 52 | + |
| 53 | +:::{figure-md} fig-version |
| 54 | + |
| 55 | + |
| 56 | +How a version spec is used to generate a version. |
| 57 | +::: |
| 58 | + |
| 59 | +The _version spec_ has a `create_version` method that takes a mapping of version component names to values. |
| 60 | + |
| 61 | +Each _version component spec_ has a `create_component` method that takes a value. The `create_version` method calls the `create_component` method for each _version component spec_ in the _version spec_ with the value from the mapping. |
| 62 | + |
| 63 | +The `create_component` assembles its own _version spec_ with the _version components_ to create a _version._ |
| 64 | + |
| 65 | +### How a version is serialized |
| 66 | + |
| 67 | +**Optional value rule.** _Version component specs_ can define an optional value. For example, numeric components have `0` as an optional value. Optional values may be omitted from the serialization as long as all dependent components also have optional values. |
| 68 | + |
| 69 | +**Required value rule.** _Version component specs_ is required if its value or the value of any of its dependent components is not optional. |
| 70 | + |
| 71 | +A valid serialization is one that contains all the components in the _version spec_ that are required based on the _required value rule._ |
| 72 | + |
| 73 | +An invalid serialization is one that does not contain all the components in the _version spec_ that are required based on the _required value rule._ |
| 74 | + |
| 75 | +An optimal serialization is the valid serialization that uses the fewest components. |
| 76 | + |
| 77 | +The `serialize` method of the _version spec_ returns either the optimal serialization or the first invalid serialization. |
| 78 | + |
| 79 | +:::{figure-md} fig-serialize-1-2-3 |
| 80 | + |
| 81 | + |
| 82 | +A version with values major=1, minor=2, and patch=3 only has one valid serialization. It is also the optimal serialization. |
| 83 | +::: |
| 84 | + |
| 85 | +:::{figure-md} fig-serialize-1-2-0 |
| 86 | + |
| 87 | + |
| 88 | +A version with values major=1, minor=2, and patch=0 has two valid serializations. The optimal serialization is the one that uses the fewest components. `1.2` in this example |
| 89 | +::: |
| 90 | + |
| 91 | +:::{figure-md} fig-serialize-1-0-0 |
| 92 | + |
| 93 | + |
| 94 | +A version with values major=1, minor=0, and patch=0 has three valid serializations. The optimal serialization is the one that uses the fewest components. `1` in this example. |
| 95 | +::: |
| 96 | + |
| 97 | +:::{figure-md} fig-serialize-1 |
| 98 | + |
| 99 | + |
| 100 | +A version with values major=1, minor=2, and patch=3 has no valid serializations in this example. The `serialize` method returns the first invalid serialization. |
| 101 | +::: |
0 commit comments