Semantic Versioning

# Semantic Versioning
## A Brief Explanation

---

# Agenda

- What is Semantic Versioning?
- Why use Semantic Versioning?
- How to use Semantic Versioning

---

# Semantic & Versioning 
**Definitions**

- **Version**: A particular form of something differing in certain respects from an earlier form or other forms of the same type of thing.
- **Semantic**: Relating to meaning in language or logic

???

Who doesn't love dictionary definitions?

You probably know what these terms mean separately,
but what do you get when you cram them together?

---

**Semantic versioning is using versioning to convey meaning.**

???

We make "version" a verb, versioning - that mystical thing
that version control systems do.

And then, and here's the key, we convey **meaning** beyond
"this thing changed" through the act of versioning.

---

# Why?

- Unifies/standardizes versioning practices
- Meaning can be leveraged by...
    - Developers
    - Managers
    - Stakeholders
    - Users
    - Programs
- Sane dependency resolution

???

Why?

So people know whats going on.

Developers, managers, stakeholders, users, dependencies - all of them like
to know "whats happening?" on a project, but all of them probably want some
different facet of that question answered.

Semantic versioning helps us do that.

---

# How?

- **Version Numbers**
    - Version numbers provide the medium to convey the meaning

- **Interfaces**
    - Provide a strict definition of what is being versioned.

- **Standardization**
    - By standardizing the format and procedures for incrementing version numbers
    they become understandable to all participants in a project

???

How?

Version numbers are the medium - the thing we communicate through

Interfaces provide the answer to "What exactly are we versioning?"

What is your projects interface? Thats for you to decide!

In a web API it's probably the endpoints

In a library it's probably the objects, methods, functions, etc
you provide.

In a command line utility it's probably the CLI syntax.

We standardize this business, so everyone can glean the information
they're looking for from the version number.

---

# The Basics

- Version numbers are minimally composed of three numbers, separated by a "."
- Each segment of the version of the version number communicates a different
    kind of change when incremented.

**$MAJOR.$MINOR.$PATCH**
- **MAJOR**: The interface has changed
- **MINOR**: Additional interface functionality is available
- **PATCH**: A bugfix has been applied

???

The very basics: How we construct the medium

Version numbers are three parts: MAJOR[dot]MINOR[dot]PATCH

(you can tack more stuff on, and you've probably definitely
seen projects that do, but lets start with the basics here)

---

# The Rules
- Must define an interface
- $X.$Y.$Z
    - No leading zeros!
- No changing releases after release!

???

The basic rules

In order to version something you have to have something to version

Leading zeros are a pain, and everyone built tooling to avoid them

After you release a version people expect it to stay the same for a
variety of reasons

- sanity
- stability
- reusability
- security
- etc

---

# The Exception

Version < 1.0.0

.center[![The Wild West](http://images.mentalfloss.com/sites/default/files/goodbadhed.jpg?resize=550x370)]

???

Every rule has it's exception. With Semantic Versioning we keep
that encapsulated below version 1.0.0, the "Wild West" period
of the project.

Changes are probably happening fast at this point, and you can
assume that no one is using your project in production (or if they are,
they've accepted the risk).

You can use the MINOR and PATCH numbers or you can ignore versioning at this
point, whatever works for you.

---

"This doesn't look like a complete specif--"

[http://semver.org/](http://semver.org/)

???

The contents of this presentation, as you've undoubtably noticed, isn't a full specification.

To avoid copy pasting the whole thing, here's the link.

A jaunt through this should clear up ambiguities, edge cases, extensions, and the like

---

# Tooling

[bumpversion](https://github.com/peritus/bumpversion)

```bash
$ bumpversion [options] part [file]
```

or a config file: .bumpversion.cfg

```bash
[bumpversion]
current_version = 0.1.0

[bumpversion:file:README.md]

[bumpversion:file:VERSION.txt]
```

???

So - this all seems well and good, but you don't want to have to keep
track of an entire specification, and how it applies to each of your projects,
entirely in your head.

Enter bumpversion

bumpversion is a handy little utility (written in python) that takes care of the
details for you, after you take the time to set it up once

---

# Why bumpversion?

- Language agnostic
- Configurable
- Extensible
- Usable
- [Well Documented](https://github.com/peritus/bumpversion/blob/master/README.rst)
- Git awareness if thats your thing
    - Auto-tag, Auto-commit
        - works nicely with github auto-release options

???

Bumpversion has a couple of great features that make it hard to justify
not using on almost any project.

- You can use it with any language
- it's configurable enough to handle most anything
- It's dead simple to use once you've set it up
- It's not hard to learn how to set up
- It ties in with the tools you're already using
    - or probably should be using

---

---