Merge pull request #124 from mattfarina/v3-rel-notes

Updating the docs for the 3.0.0 release

CHANGELOG.md

@@ -1,10 +1,47 @@
-# 1.5.0 (2019-09-11)
+# Changelog
 
-## Added
+## 3.0.0 (2019-09-12)
+
+This is a major release of the semver package which includes API changes. The Go
+API is compatible with ^1. The Go API was not changed because many people are using
+`go get` without Go modules for their applications and API breaking changes cause
+errors which we have or would need to support.
+
+The changes in this release are the handling based on the data passed into the
+functions. These are described in the added and changed sections below.
+
+### Added
+
+- StrictNewVersion function. This is similar to NewVersion but will return an
+  error if the version passed in is not a strict semantic version. For example,
+  1.2.3 would pass but v1.2.3 or 1.2 would fail because they are not strictly
+  speaking semantic versions. This function is faster, performs fewer operations,
+  and uses fewer allocations than NewVersion.
+- Fuzzing has been performed on NewVersion, StrictNewVersion, and NewConstraint.
+  The Makefile contains the operations used. For more information on you can start
+  on Wikipedia at https://en.wikipedia.org/wiki/Fuzzing
+- Now using Go modules
+
+### Changed
+
+- NewVersion has proper prerelease and metadata validation with error messages
+  to signal an issue with either of them
+- ^ now operates using a similar set of rules to npm/js and Rust/Cargo. If the
+  version is >=1 the ^ ranges works the same as v1. For major versions of 0 the
+  rules have changed. The minor version is treated as the stable version unless
+  a patch is specified and then it is equivalent to =. One difference from npm/js
+  is that prereleases there are only to a specific version (e.g. 1.2.3).
+  Prereleases here look over multiple versions and follow semantic version
+  ordering rules. This pattern now follows along with the expected and requested
+  handling of this packaged by numerous users.
+
+## 1.5.0 (2019-09-11)
+
+### Added
 
 - #103: Add basic fuzzing for `NewVersion()` (thanks @jesse-c)
 
-## Changed
+### Changed
 
 - #82: Clarify wildcard meaning in range constraints and update tests for it (thanks @greysteil)
 - #83: Clarify caret operator range for pre-1.0.0 dependencies (thanks @greysteil)
@@ -13,97 +50,111 @@
 - #89: Test with new go versions (thanks @thedevsaddam)
 - #87: Added $ to ValidPrerelease for better validation (thanks @jeremycarroll)
 
-## Fixed
+### Fixed
 
 - #78: Fix unchecked error in example code (thanks @ravron)
 - #70: Fix the handling of pre-releases and the 0.0.0 release edge case
 - #97: Fixed copyright file for proper display on GitHub
 - #107: Fix handling prerelease when sorting alphanum and num 
 - #109: Fixed where Validate sometimes returns wrong message on error
 
-# 1.4.2 (2018-04-10)
+## 1.4.2 (2018-04-10)
+
+### Changed
 
-## Changed
 - #72: Updated the docs to point to vert for a console appliaction
 - #71: Update the docs on pre-release comparator handling
 
-## Fixed
+### Fixed
+
 - #70: Fix the handling of pre-releases and the 0.0.0 release edge case
 
-# 1.4.1 (2018-04-02)
+## 1.4.1 (2018-04-02)
+
+### Fixed
 
-## Fixed
 - Fixed #64: Fix pre-release precedence issue (thanks @uudashr)
 
-# 1.4.0 (2017-10-04)
+## 1.4.0 (2017-10-04)
+
+### Changed
 
-## Changed
 - #61: Update NewVersion to parse ints with a 64bit int size (thanks @zknill)
 
-# 1.3.1 (2017-07-10)
+## 1.3.1 (2017-07-10)
+
+### Fixed
 
-## Fixed
 - Fixed #57: number comparisons in prerelease sometimes inaccurate
 
-# 1.3.0 (2017-05-02)
+## 1.3.0 (2017-05-02)
+
+### Added
 
-## Added
 - #45: Added json (un)marshaling support (thanks @mh-cbon)
 - Stability marker. See https://masterminds.github.io/stability/
 
-## Fixed
+### Fixed
+
 - #51: Fix handling of single digit tilde constraint (thanks @dgodd)
 
-## Changed
+### Changed
+
 - #55: The godoc icon moved from png to svg
 
-# 1.2.3 (2017-04-03)
+## 1.2.3 (2017-04-03)
+
+### Fixed
 
-## Fixed
 - #46: Fixed 0.x.x and 0.0.x in constraints being treated as *
 
-# Release 1.2.2 (2016-12-13)
+## Release 1.2.2 (2016-12-13)
+
+### Fixed
 
-## Fixed
 - #34: Fixed issue where hyphen range was not working with pre-release parsing.
 
-# Release 1.2.1 (2016-11-28)
+## Release 1.2.1 (2016-11-28)
+
+### Fixed
 
-## Fixed
 - #24: Fixed edge case issue where constraint "> 0" does not handle "0.0.1-alpha"
   properly.
 
-# Release 1.2.0 (2016-11-04)
+## Release 1.2.0 (2016-11-04)
+
+### Added
 
-## Added
 - #20: Added MustParse function for versions (thanks @adamreese)
 - #15: Added increment methods on versions (thanks @mh-cbon)
 
-## Fixed
+### Fixed
+
 - Issue #21: Per the SemVer spec (section 9) a pre-release is unstable and
   might not satisfy the intended compatibility. The change here ignores pre-releases
   on constraint checks (e.g., ~ or ^) when a pre-release is not part of the
   constraint. For example, `^1.2.3` will ignore pre-releases while
   `^1.2.3-alpha` will include them.
 
-# Release 1.1.1 (2016-06-30)
+## Release 1.1.1 (2016-06-30)
+
+### Changed
 
-## Changed
 - Issue #9: Speed up version comparison performance (thanks @sdboyer)
 - Issue #8: Added benchmarks (thanks @sdboyer)
 - Updated Go Report Card URL to new location
 - Updated Readme to add code snippet formatting (thanks @mh-cbon)
 - Updating tagging to v[SemVer] structure for compatibility with other tools.
 
-# Release 1.1.0 (2016-03-11)
+## Release 1.1.0 (2016-03-11)
 
 - Issue #2: Implemented validation to provide reasons a versions failed a
   constraint.
 
-# Release 1.0.1 (2015-12-31)
+## Release 1.0.1 (2015-12-31)
 
 - Fixed #1: * constraint failing on valid versions.
 
-# Release 1.0.0 (2015-10-20)
+## Release 1.0.0 (2015-10-20)
 
 - Initial release

README.md

@@ -18,33 +18,36 @@ If you are looking for a command line tool for version comparisons please see
 
 There are three major versions fo the `semver` package.
 
-* 3.x.x which is currently under development. This version is focused on compatibility
-  SemVer handling in other tools from other language. It will have a similar API
-  to the 1.x.x releases. The development of this version is on the master branch.
+* 3.x.x is the new stable and active version. This version is focused on constraint
+  compatibility for range handling in other tools from other languages. It has
+  a similar API to the v1 releases. The development of this version is on the master
+  branch. The documentation for this version is below.
 * 2.x was developed primarily for [dep](https://github.com/golang/dep). There are
   no tagged releases and the development was performed by [@sdboyer](https://github.com/sdboyer).
-  This version lives on the 2.x branch.
+  There are API breaking changes from v1. This version lives on the [2.x branch](https://github.com/Masterminds/semver/tree/2.x).
 * 1.x.x is the most widely used version with numerous tagged releases. This is the
-  current stable. The development, to fix bugs, occurs on the release-1 branch.
+  previous stable and is still maintained for bug fixes. The development, to fix
+  bugs, occurs on the release-1 branch. You can read the documentation [here](https://github.com/Masterminds/semver/blob/release-1/README.md).
 
 ## Parsing Semantic Versions
 
 There are two functions that can parse semantic versions. The `StrictNewVersion`
 function only parses valid version 2 semantic versions as outlined in the
 specification. The `NewVersion` function attempts to coerce a version into a
 semantic version and parse it. For example, if there is a leading v or a version
-listed without all 3 parts (e.g. 1.2) it will attempt to coerce it into a valid
+listed without all 3 parts (e.g. `v1.2`) it will attempt to coerce it into a valid
 semantic version (e.g., 1.2.0). In both cases a `Version` object is returned
 that can be sorted, compared, and used in constraints.
 
-When parsing a version an optional error can be returned if there is an issue
-parsing the version. For example,
+When parsing a version an error is returned if there is an issue parsing the
+version. For example,
 
     v, err := semver.NewVersion("1.2.3-beta.1+build345")
 
 The version object has methods to get the parts of the version, compare it to
 other versions, convert the version back into a string, and get the original
-string.
+string. Getting the original string is useful if the semantic version was coerced
+into a valid form.
 
 ## Sorting Semantic Versions
 
@@ -69,26 +72,26 @@ sort.Sort(semver.Collection(vs))
 ## Checking Version Constraints
 
 There are two methods for comparing versions. One uses comparison methods on
-`Version` instances and the other is using Constraints. There are some important
+`Version` instances and the other uses `Constraints`. There are some important
 differences to notes between these two methods of comparison.
 
 1. When two versions are compared using functions such as `Compare`, `LessThan`,
    and others it will follow the specification and always include prereleases
-   within the comparison. It will provide an answer valid with the comparison
-   spec section at https://semver.org/#spec-item-11
+   within the comparison. It will provide an answer that is valid with the
+   comparison section of the spec at https://semver.org/#spec-item-11
 2. When constraint checking is used for checks or validation it will follow a
    different set of rules that are common for ranges with tools like npm/js
    and Rust/Cargo. This includes considering prereleases to be invalid if the
-   ranges does not include on. If you want to have it include pre-releases a
+   ranges does not include one. If you want to have it include pre-releases a
    simple solution is to include `-0` in your range.
-3. Constraint ranges can have some complex rules including the shorthard use of
+3. Constraint ranges can have some complex rules including the shorthand use of
    ~ and ^. For more details on those see the options below.
 
 There are differences between the two methods or checking versions because the
 comparison methods on `Version` follow the specification while comparison ranges
 are not part of the specification. Different packages and tools have taken it
 upon themselves to come up with range rules. This has resulted in differences.
-For example, npm/js and Cargo/Rust follow similar patterns which PHP has a
+For example, npm/js and Cargo/Rust follow similar patterns while PHP has a
 different pattern for ^. The comparison features in this package follow the
 npm/js and Cargo/Rust lead because applications using it have followed similar
 patters with their versions.
@@ -113,8 +116,8 @@ a := c.Check(v)
 ### Basic Comparisons
 
 There are two elements to the comparisons. First, a comparison string is a list
-of comma separated AND comparisons. These are then separated by || (OR)
-comparisons. For example, `">= 1.2, < 3.0.0 || >= 4.2.3"` is looking for a
+of space or comma separated AND comparisons. These are then separated by || (OR)
+comparisons. For example, `">= 1.2 < 3.0.0 || >= 4.2.3"` is looking for a
 comparison that's greater than or equal to 1.2 and less than 3.0.0 or is
 greater than or equal to 4.2.3.
 
@@ -147,7 +150,9 @@ at a list of releases while `>=1.2.3-0` will evaluate and find prereleases.
 
 The reason for the `0` as a pre-release version in the example comparison is
 because pre-releases can only contain ASCII alphanumerics and hyphens (along with
-`.` separators), per the spec. Sorting happens in ASCII sort order, again per the spec. The lowest character is a `0` in ASCII sort order (see an [ASCII Table](http://www.asciitable.com/))
+`.` separators), per the spec. Sorting happens in ASCII sort order, again per the
+spec. The lowest character is a `0` in ASCII sort order
+(see an [ASCII Table](http://www.asciitable.com/))
 
 Understanding ASCII sort ordering is important because A-Z comes before a-z. That
 means `>=1.2.3-BETA` will return `1.2.3-alpha`. What you might expect from case
@@ -159,14 +164,14 @@ the spec specifies.
 There are multiple methods to handle ranges and the first is hyphens ranges.
 These look like:
 
-* `1.2 - 1.4.5` which is equivalent to `>= 1.2, <= 1.4.5`
-* `2.3.4 - 4.5` which is equivalent to `>= 2.3.4, <= 4.5`
+* `1.2 - 1.4.5` which is equivalent to `>= 1.2 <= 1.4.5`
+* `2.3.4 - 4.5` which is equivalent to `>= 2.3.4 <= 4.5`
 
 ### Wildcards In Comparisons
 
 The `x`, `X`, and `*` characters can be used as a wildcard character. This works
 for all comparison operators. When used on the `=` operator it falls
-back to the pack level comparison (see tilde below). For example,
+back to the patch level comparison (see tilde below). For example,
 
 * `1.2.x` is equivalent to `>= 1.2.0, < 1.3.0`
 * `>= 1.2.x` is equivalent to `>= 1.2.0`