Pin
Introduction
You have a software project. You've written code, written tests, and configured build tools. Your project consists of lots of files, and you are probably tracking the changes to these files with some kind of version control software like Git. Other developers can view your Git repository to see the changes to these files over time.
You also release your software. The stuff that make up your release is derived from your source code, whether you're building a binary, transforming TypeScript files into JavaScript + type definition files, or simply providing copies of a subset of your source code. For these published artifacts, there are a different set of changes that the consumers, your users, care about: the observable changes to your app, API, etc.
Pin is the version control system for your releases.
How are release versions used?
Why do releases have versions?
- It is important to be able to tie a published version of your software to the exact state of your source code. This helps identify bugs, mainly.
- Release versions communicate when upgrades may be available, such as when the latest version is a higher number than what a user has installed.
- They can be used for marketing.
Any system that helps to manage release versioning should support all of these goals. A good system does this without imposing restrictions on how you use your other tools. That is the goal of Pin.
How Pin Works
Goals
Pin enables you to...
- ...document your changes as you make them, asynchronously from your release workflow.
- ...generate/update your CHANGELOG from those individual change documents.
- ...know which changes are new since your previous release.
- ...know what your next release version should be, based on the changes.
- ...have a tool that can automate all of these steps.
Pin does not...
- ...depend on how you version-control your source code.
- ...require a specific versioning scheme. You can use SemVer, date-based versions, build number, names of cartoon characters, or anything else.
Workflow
- You complete a feature, a bug fix, or any other change that affects your published artifacts.
- You describe the changes in a Changefile.
- When you release your software, you put the pending Changefiles in a directory naming the release version.
Changefiles
When you have finished a feature, fixed a bug, or made any other change that is observable in your publishable artifacts, you create a Changefile to document this change.
A Changefile is a file called <timestamp>.chg
that lives alongside your project. It is written in TOML
, YAML
or JSON
syntax, and saved in a .pin
directory at the root the project it describes.
The <timestamp>
portion of the Changefile is in yyyymmddhhmmss
format.
example-project/
.pin/
20200305142743.chg
Fields
The following table shows required fields and some canonical non-required fields. Any additional fields other than these may be added for your own usage.
Field name |
Type |
Required |
Description |
summary |
String |
x |
This field provides a summary of what is introduced by this change. |
details |
String |
|
Use this field to provide additional details about the change. |
level |
String |
x |
This field indicates the level of change this Changefile describes. For example, if your project uses Semantic Versioning, the level might be "major", "minor", or "patch". |
tickets |
List of Strings |
|
Use this field to mention tickets that are closed by this change. |
components |
List of { [component: String]: String } dictionaries. |
|
Use this to provide additional details about specific components. |
A Complete Example
See the examples
directory.
Releasing your code
When you release your software, create a new release directory inside the .pin
directory, and put your pending Changefiles into it.
.pin/
v3.2.1/
20270829155834.chg
20380608070126.chg
20560823233913.chg