pin

README

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

1. You complete a feature, a bug fix, or any other change that affects your published artifacts.
2. You describe the changes in a Changefile.
3. 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