release: prepare 0.2.0 (#63)

* docs(readme): update readme

* docs(readme): note on friendly contribution

* docs(changelog): fill v0.1.0 section

* docs(changelog): fill v0.2.0 section

* docs(changelog): add a summary of the release

* docs(readme): everyone welcome message

* docs(changelog): update unreleased diff

* build(cargo.toml): add Jacob to authors

* build(cargo.toml): update crate version

* docs(changelog): fix unreleased diff link

* docs(changelog): improve changelog

Co-authored-by: Alex Tokarev <[email protected]>

* docs(changelog): change ErrorShouldCancel

Co-authored-by: Alex Tokarev <[email protected]>

* docs(changelog): rephrasing

Co-authored-by: Alex Tokarev <[email protected]>

* docs(changelog): proper capitalization for GitHub

Co-authored-by: Alex Tokarev <[email protected]>

* docs(changelog): update v02 release date

* docs(readme): use 'pink' for guide badge

Co-authored-by: Alex Tokarev <[email protected]>

* fix: make `cargo publish --dry-run` work

Co-authored-by: Jacob Finkelman <[email protected]>

Author: 2 people

.commitlintrc.yml

@@ -1,10 +1,12 @@
 extends:
   - '@commitlint/config-conventional'
 
+# https://commitlint.js.org/#/reference-rules
 rules:
-  footer-max-line-length: [ 2, 'always', 72 ]
   header-max-length: [ 2, 'always', 72 ]
-  body-max-line-length: [ 2, 'always', 72 ]
+  body-max-line-length: [ 1, 'always', 72 ]
+  footer-max-line-length: [ 1, 'always', 72 ]
+  footer-leading-blank: [ 1, 'always' ]
   type-enum: [
       2,
       'always',
@@ -16,6 +18,7 @@ rules:
         'fix',
         'perf',
         'refactor',
+        'release',
         'revert',
         'style',
         'test',

.github/workflows/ci.yml

@@ -111,4 +111,3 @@ jobs:
         uses: wagoid/commitlint-github-action@v2
         with:
           configFile: .commitlintrc.yml
-          failOnWarnings: true

CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased [(diff)][diff-unreleased]
+
+## [0.2.0] - 2020-11-19 - [(diff with 0.1.0)][diff-0.2.0]
+
+This release brings many important improvements to PubGrub.
+The gist of it is:
+
+- A bug in the algorithm's implementation was [fixed](https://github.com/pubgrub-rs/pubgrub/pull/23).
+- The solver is now implemented in a `resolve` function taking as argument
+  an implementer of the `DependencyProvider` trait,
+  which has more control over the decision making process.
+- End-to-end property testing of large synthetic registries was added.
+- More than 10x performance improvement.
+
+### Changes affecting the public API
+
+#### Added
+
+- Links to code items in the code documenation.
+- New `"serde"` feature that allows serializing some library types, useful for making simple reproducible bug reports.
+- New variants for `error::PubGrubError` which are `DependencyOnTheEmptySet`,
+  `SelfDependency`, `ErrorChoosingPackageVersion` and `ErrorInShouldCancel`.
+- New `type_alias::Map` defined as `rustc_hash::FxHashMap`.
+- New `type_alias::SelectedDependencies<P, V>` defined as `Map<P, V>`.
+- The types `Dependencies` and `DependencyConstraints` were introduced to clarify intent.
+- New function `choose_package_with_fewest_versions` to help implement
+  the `choose_package_version` method of a `DependencyProvider`.
+- Implement `FromStr` for `SemanticVersion`.
+- Add the `VersionParseError` type for parsing of semantic versions.
+
+#### Changed
+
+- The `Solver` trait was replaced by a `DependencyProvider` trait
+  which now must implement a `choose_package_version` method
+  instead of `list_available_versions`.
+  So it now has the ability to choose a package in addition to a version.
+  The `DependencyProvider` also has a new optional method `should_cancel`
+  that may be used to stop the solver if needed.
+- The `choose_package_version` and `get_dependencies` methods of the
+  `DependencyProvider` trait now take an immutable reference to `self`.
+  Interior mutability can be used by implementor if mutability is needed.
+- The `Solver.run` method was thus replaced by a free function `solver::resolve`
+  taking a dependency provider as first argument.
+- The `OfflineSolver` is thus replaced by an `OfflineDependencyProvider`.
+- `SemanticVersion` now takes `u32` instead of `usize` for its 3 parts.
+- `NumberVersion` now uses `u32` instead of `usize`.
+
+#### Removed
+
+- `ErrorRetrievingVersions` variant of `error::PubGrubError`.
+
+### Changes in the internal parts of the API
+
+#### Added
+
+- `benches/large_case.rs` enables benchmarking of serialized registries of packages.
+- `examples/caching_dependency_provider.rs` an example dependency provider caching dependencies.
+- `PackageTerm<P, V> = (P, Term<V>)` new type alias for readability.
+- `Memory.term_intersection_for_package(&mut self, package: &P) -> Option<&Term<V>>`
+- New types were introduces for conflict resolution in `internal::partial_solution`
+  to clarify the intent and return values of some functions.
+  Those types are `DatedAssignment` and `SatisfierAndPreviousHistory`.
+- `PartialSolution.term_intersection_for_package` calling the same function
+  from its `memory`.
+- New property tests for ranges: `negate_contains_opposite`, `intesection_contains_both`
+  and `union_contains_either`.
+- A large synthetic test case was added in `test-examples/`.
+- A new test example `double_choices` was added
+  for the detection of a bug (fixed) in the implementation.
+- Property testing of big synthetic datasets was added in `tests/proptest.rs`.
+- Comparison of PubGrub solver and a SAT solver
+  was added with `tests/sat_dependency_provider.rs`.
+- Other regression and unit tests were added to `tests/tests.rs`.
+
+#### Changed
+
+- CI workflow was improved (`./github/workflows/`), including a check for [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) and [Clippy ](https://github.com/rust-lang/rust-clippy) for source code linting.
+- Using SPDX license identifiers instead of MPL-2.0 classic file headers.
+- `State.incompatibilities` is now wrapped inside a `Rc`.
+- `DecisionLevel(u32)` is used in place of `usize` for partial solution decision levels.
+- `State.conflict_resolution` now also returns the almost satisfied package
+  to avoid an unnecessary call to `self.partial_solution.relation(...)` after conflict resolution.
+- `Kind::NoVersion` renamed to `Kind::NoVersions` and all other usage of `noversion`
+  has been changed to `no_versions`.
+- Variants of the `incompatibility::Relation` enum have changed.
+- Incompatibility now uses a deterministic hasher to store packages in its hash map.
+- `incompatibility.relation(...)` now takes a function as argument to avoid computations
+  of unnecessary terms intersections.
+- `Memory` now uses a deterministic hasher instead of the default one.
+- `memory::PackageAssignments` is now an enum instead of a struct.
+- Derivations in a `PackageAssignments` keep a precomputed intersection of derivation terms.
+- `potential_packages` method now returns a `Range`
+  instead of a `Term` for the versions constraint of each package.
+- `PartialSolution.relation` now takes `&mut self` instead of `&self`
+  to be able to store computation of terms intersection.
+- `Term.accept_version` was renamed `Term.contains`.
+- The `satisfied_by` and `contradicted_by` methods of a `Term`
+  now directly takes a reference to the intersection of other terms.
+  Same for `relation_with`.
+
+#### Removed
+
+- `term` field of an `Assignment::Derivation` variant.
+- `Memory.all_terms` method was removed.
+- `Memory.remove_decision` method was removed in favor of a check before using `Memory.add_decision`.
+- `PartialSolution` methods `pick_package` and `pick_version` have been removed
+  since control was given back to the dependency provider to choose a package version.
+- `PartialSolution` methods `remove_last_decision` and `satisfies_any_of` were removed
+  in favor of a preventive check before calling `add_decision`.
+- `Term.is_negative`.
+
+#### Fixed
+
+- Prior cause computation (`incompatibility::prior_cause`) now uses the intersection of package terms
+  instead of their union, which was an implementation error.
+
+## [0.1.0] - 2020-10-01
+
+### Added
+
+- `README.md` as the home page of this repository.
+- `LICENSE`, code is provided under the MPL 2.0 license.
+- `Cargo.toml` configuration of this Rust project.
+- `src/` containing all the source code for this first implementation of PubGrub in Rust.
+- `tests/` containing test end-to-end examples.
+- `examples/` other examples, not in the form of tests.
+- `.gitignore` configured for a Rust project.
+- `.github/workflows/` CI to automatically build, test and document on push and pull requests.
+
+[0.2.0]: https://github.com/pubgrub-rs/pubgrub/releases/tag/v0.2.0
+[0.1.0]: https://github.com/pubgrub-rs/pubgrub/releases/tag/v0.1.0
+[diff-unreleased]: https://github.com/pubgrub-rs/pubgrub/compare/release...dev
+[diff-0.2.0]: https://github.com/mpizenberg/elm-pointer-events/compare/v0.1.0...v0.2.0

Cargo.toml

@@ -2,16 +2,16 @@
 
 [package]
 name = "pubgrub"
-version = "0.1.0"
-authors = ["Matthieu Pizenberg <[email protected]>", "Alex Tokarev <[email protected]>"]
+version = "0.2.0"
+authors = ["Matthieu Pizenberg <[email protected]>", "Alex Tokarev <[email protected]>", "Jacob Finkelman <[email protected]>"]
 edition = "2018"
 description = "PubGrub version solving algorithm"
 readme = "README.md"
 repository = "https://github.com/mpizenberg/pubgrub-rs"
 license = "MPL-2.0"
 keywords = ["dependency", "pubgrub", "semver", "solver", "version"]
 categories = ["algorithms"]
-include = ["Cargo.toml", "LICENSE", "README.md", "src/**", "tests/**", "examples/**"]
+include = ["Cargo.toml", "LICENSE", "README.md", "src/**", "tests/**", "examples/**", "benches/**"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 

README.md

@@ -1,12 +1,17 @@
-# PubGrub version solving algorithm.
+# PubGrub version solving algorithm
 
-It consists in efficiently finding a set of packages and versions
+![license](https://img.shields.io/crates/l/pubgrub.svg)
+[![crates.io](https://img.shields.io/crates/v/pubgrub.svg?logo=rust)][crates]
+[![docs.rs](https://img.shields.io/badge/docs.rs-pubgrub-yellow)][docs]
+[![guide](https://img.shields.io/badge/guide-pubgrub-pink?logo=read-the-docs)][guide]
+
+Version solving consists in efficiently finding a set of packages and versions
 that satisfy all the constraints of a given project dependencies.
 In addition, when that is not possible,
 PubGrub tries to provide a very human-readable and clear
 explanation as to why that failed.
-Below is an example of an explanation present in
-the introductory blog post about PubGrub.
+The [introductory blog post about PubGrub][medium-pubgrub] presents
+one such example of failure explanation:
 
 ```txt
 Because dropdown >=2.0.0 depends on icons >=2.0.0 and
@@ -23,37 +28,32 @@ So, because root depends on both menu >=1.0.0 and intl >=5.0.0,
   version solving failed.
 ```
 
-The algorithm is generic and works for any type of dependency system
+This pubgrub crate provides a Rust implementation of PubGrub.
+It is generic and works for any type of dependency system
 as long as packages (P) and versions (V) implement
-the `Package` and `Version` traits.
-`Package` is strictly equivalent and automatically generated
-for any type that implement `Clone + Eq + Hash + Debug + Display`.
-`Version` simply states that versions are ordered,
-that there should be
-a minimal `lowest` version (like 0.0.0 in semantic versions),
-and that for any version, it is possible to compute
-what the next version closest to this one is (`bump`).
-For semantic versions, `bump` corresponds to an increment of the patch number.
-
+the provided `Package` and `Version` traits.
 
-## API
 
-```rust
-let solution = resolve(&dependency_provider, package, version)?;
-```
+## Using the pubgrub crate
 
-Where `dependency_provider` supplies the list of available packages and versions,
-as well as the dependencies of every available package
-by implementing the `DependencyProvider` trait.
-The call to `resolve` for a given package at a given version
-will compute the set of packages and versions needed
-to satisfy the dependencies of that package and version pair.
-If there is no solution, the reason will be provided as clear as possible.
+A [guide][guide] with both high-level explanations and
+in-depth algorithm details is available online.
+The [API documentation is available on docs.rs][docs].
+A version of the [API docs for the unreleased functionality][docs-dev] from `dev` branch is also
+accessible for convenience.
 
 
 ## Contributing
 
-Discussion and development happens here on github and on our [Zulip stream](https://rust-lang.zulipchat.com/#narrow/stream/260232-t-cargo.2FPubGrub). Please join in!
+Discussion and development happens here on GitHub and on our
+[Zulip stream](https://rust-lang.zulipchat.com/#narrow/stream/260232-t-cargo.2FPubGrub).
+Please join in!
+
+Remember to always be considerate of others,
+who may have different native languages, cultures and experiences.
+We want everyone to feel welcomed,
+let us know with a private message on Zulip if you don't feel that way.
+
 
 ## PubGrub
 
@@ -66,12 +66,18 @@ An introductory blog post was
 [published on Medium][medium-pubgrub] by its author.
 
 The detailed explanation of the algorithm is
-[provided on GitHub][github-pubgrub].
+[provided on GitHub][github-pubgrub],
+and complemented by the ["Internals" section of our guide][guide-internals].
 The foundation of the algorithm is based on ASP (Answer Set Programming),
 and a book called
 "[Answer Set Solving in Practice][potassco-book]"
 by Martin Gebser, Roland Kaminski, Benjamin Kaufmann and Torsten Schaub.
 
+[crates]: https://crates.io/crates/pubgrub
+[guide]: https://pubgrub-rs-guide.netlify.app/
+[guide-internals]: https://pubgrub-rs-guide.netlify.app/internals/intro.html
+[docs]: https://docs.rs/pubgrub
+[docs-dev]: https://pubgrub-rs.github.io/pubgrub/pubgrub/
 [medium-pubgrub]: https://medium.com/@nex3/pubgrub-2fb6470504f
 [github-pubgrub]: https://github.com/dart-lang/pub/blob/master/doc/solver.md
 [potassco-book]: https://potassco.org/book/

src/lib.rs

@@ -206,6 +206,7 @@
 //! with a cache, you may want to know that some versions
 //! do not exist in your cache.
 
+#![allow(clippy::rc_buffer)]
 #![warn(missing_docs)]
 
 pub mod error;