A draft for a stability guide

DEVELOPMENT.md

@@ -4,24 +4,17 @@
 
  * **test-first development**
    * protect against regression and make implementing features easy.
-   * user docker to test more elaborate user interactions
+   * user containers to test more elaborate user interactions
    * keep it practical, knowing the Rust compiler already has your back
      for the mundane things, like unhappy code paths.
    * *use git itself* as reference implementation, and use their test-cases and fixtures where
-     appropriate.
-   * *use libgit2* test fixtures and cases where appropriate.
+     appropriate. At the very least, try to learn from them.
+   * *use libgit2* test fixtures and cases where appropriate, or learn from them.
  * **safety first**
    * handle all errors, never `unwrap()`. If needed, `expect("why")`.
-   * provide an error chain and make it easy to understand what went wrong.
- * **strive for an MVP and version 1.0 fast...**
-   * ...even if that includes only the most common usecases.
- * **Prefer to increment major version rapidly...**
-   * ...instead of keeping major version zero for longer than needed.
- * **stability**
-   * we adhere to semantic versioning
-   * while below 1.0, expect a greater amount of breaking changes, which are announced with minor versions
-   * From 1.0, we will try hardest to keep the API and user interface non-breaking the closer to the user a library is. Thus the CLI should remain at version
-    1 for a long time. However, crates that make it up can change more rapidly and may see more major version changes over time.
+   * provide an error chain and make it easy to understand what went wrong. We use `quick-error` for non-generic errors and `thiserror` when generalization is
+     needed.
+ * Adhere to the [stability guide](https://github.com/Byron/gitoxide/blob/main/STABILITY.md)
 
 ## General
 

LICENSE-APACHE

@@ -176,7 +176,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2020 Sebastian Thiel
+   Copyright 2018-2021 Sebastian Thiel, and [contributors](https://github.com/byron/gitoxide/contributors)
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

LICENSE-MIT

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018-2020 Sebastian Thiel, and [others](https://github.com/byron/gitoxide/contributors).
+Copyright (c) 2018-2021 Sebastian Thiel, and [contributors](https://github.com/byron/gitoxide/contributors).
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile

@@ -129,7 +129,14 @@ check: ## Build all code in suitable configurations
 					&& cargo check --features async-client
 	cd git-protocol && if cargo check --all-features 2>/dev/null; then false; else true; fi
 	cd git-repository && cargo check --all-features \
+					  && cargo check --no-default-features --features local \
+					  && cargo check --no-default-features --features network \
 					 && cargo check --no-default-features
+	cd cargo-smart-release && cargo check
+	cd experiments/object-access && cargo check
+	cd experiments/diffing && cargo check
+	cd experiments/traversal && cargo check
+	cd experiments/hash-owned-borrowed && cargo check
 
 unit-tests: ## run all unit tests
 	cargo test --all

README.md

@@ -48,8 +48,15 @@ Please see _'Development Status'_ for a listing of all crates and their capabili
 
 ### Crates
 
-Follow linked crate name for detailed status.
+Follow linked crate name for detailed status. Please note that all crates follow [semver] as well as the [stability guide].
 
+### Released
+
+* **Stability Tier 2**
+  - [git-tempfile](https://github.com/Byron/gitoxide/blob/main/git-tempfile/README.md)
+  - [git-lock](https://github.com/Byron/gitoxide/blob/main/git-lock/README.md)
+
+### In Development/Pre-Release
 * **usable**
   * [git-actor](https://github.com/Byron/gitoxide/blob/main/crate-status.md#git-actor)
   * [git-hash](https://github.com/Byron/gitoxide/blob/main/crate-status.md#git-hash)
@@ -66,9 +73,8 @@ Follow linked crate name for detailed status.
   * [git-traverse](https://github.com/Byron/gitoxide/blob/main/crate-status.md#git-traverse)
   * [git-config](https://github.com/Byron/gitoxide/blob/main/crate-status.md#git-config)
   * [git-features](https://github.com/Byron/gitoxide/blob/main/crate-status.md#git-features)
-  * [git-tempfile](https://github.com/Byron/gitoxide/blob/main/crate-status.md#git-tempfile)
-  * [git-lock](https://github.com/Byron/gitoxide/blob/main/crate-status.md#git-lock)
   * [git-ref](https://github.com/Byron/gitoxide/blob/main/crate-status.md#git-ref)
+  * `gitoxide-core`
 * **very early**    
   * [git-repository](https://github.com/Byron/gitoxide/blob/main/crate-status.md#git-repository)
 * **idea**
@@ -83,39 +89,18 @@ Follow linked crate name for detailed status.
   * [x] Generate and verify large commit graphs
   * [ ] Generate huge pack from a lot of loose objects
 
-### Ideas for Examples
-
-  * [ ] `gix tool open-remote` open the URL of the remote, possibly after applying known transformations to go from `ssh` to `https`.
-  * [ ] Open up SQL for git using [sqlite virtual tables](https://github.com/rusqlite/rusqlite/blob/master/tests/vtab.rs). Check out gitqlite
-        as well. What would an MVP look like? Maybe even something that could ship with gitoxide.
-  * [ ] A truly awesome history rewriter which makes it easy to understand what happened while avoiding all pitfalls. Think BFG, but more awesome, if that's possible.
-  * [ ] `git-tui` should learn a lot from [fossil-scm] regarding the presentation of data. Maybe [this](https://github.com/Lutetium-Vanadium/requestty/) can be used for prompts.
-  * [ ] Can markdown be used as database so issue-trackers along with meta-data could just be markdown files which are mostly human-editable? Could user interfaces
-        be meta-data aware and just hide the meta-data chunks which are now editable in the GUI itself? Doing this would make conflicts easier to resolve than an `sqlite`
-        database.
-      * ~~A git-backend for `sqlite` which should allow embedding sqlite databases into git repositories, which in turn can be used for bug-trackers, wikis or other
-        features, making for a fully distributed github like experience, maybe.~~
-
-### Ideas for Spin-Offs
-
-* [ ] A system to integrate tightly with `git-lfs` to allow a multi-tier architecture so that assets can be stored in git and are accessible quickly from an intranet location
-  (for example by accessing the storage read-only over the network) while changes are pushed immediately by the server to other edge locations, like _the cloud_ or backups. Sparse checkouts along with explorer/finder integrations
-  make it convenient to only work on a small subset of files locally. Clones can contain all configuration somebody would need to work efficiently from their location,
-  and authentication for the git history as well as LFS resources make the system secure. One could imagine encryption support for untrusted locations in _the cloud_
-  even though more research would have to be done to make it truly secure.
-* [ ] A [syncthing] like client/server application. This is to demonstrate how lower-level crates can be combined into custom applications that use
-  only part of git's technology to achieve their very own thing. Watch out for big file support, multi-device cross-syncing, the possibility for
-  untrusted destinations using full-encryption, case-insensitive and sensitive filesystems, and extended file attributes as well as ignore files.
-
-[syncthing]: https://github.com/syncthing/syncthing
-[fossil-scm]: https://www.fossil-scm.org
-
 ### Cargo features
 
 Many crates use feature flags to allow tuning the compiled result based on your needs. Have a [look at the guide][cargo-features] for more information.
 
 [cargo-features]: https://github.com/Byron/gitoxide/blob/main/cargo-features.md#git-config
 
+### Stability
+
+Our [stability guide] helps to judge how much churn can be expected when depending on crates in this workspace.
+
+[stability guide]: https://github.com/Byron/gitoxide/blob/main/STABILITY.md
+
 ## Installation
 
 ### Download a Binary Release
@@ -208,7 +193,7 @@ Project non-goals can change over time as we learn more, and they can be challen
      long running operations.
    * When connecting or streaming over TCP connections, especially when receiving on the server, async seems like a must
      though, but behind a feature flag.
-     
+
 ## Contributions
 
 If what you have seen so far sparked your interest to contribute, then let us say: We are happy to have you and help you to get started.
@@ -218,6 +203,9 @@ We recommend running `make tests check-size` during the development process to a
 A backlog for work ready to be picked up is [available in the Project's Kanban board][project-board], which contains instructions on how 
 to pick a task. If it's empty or you have other questions, feel free to [start a discussion][discussions] or reach out to @Byron [privately][keybase].
 
+For additional details, also take a look at the [collaboration guide].
+
+[collaboration guide]: https://github.com/Byron/gitoxide/blob/main/COLLABORATING.md
 [project-board]: https://github.com/Byron/gitoxide/projects
 [discussions]: https://github.com/Byron/gitoxide/discussions
 [keybase]: https://keybase.io/byronbates
@@ -234,7 +222,34 @@ Provide a CLI to for the most basic user journey:
 * [ ] add a remote
 * [ ] push
   * [ ] create (thin) pack
-
+
+### Ideas for Examples
+
+* [ ] `gix tool open-remote` open the URL of the remote, possibly after applying known transformations to go from `ssh` to `https`.
+* [ ] Open up SQL for git using [sqlite virtual tables](https://github.com/rusqlite/rusqlite/blob/master/tests/vtab.rs). Check out gitqlite
+  as well. What would an MVP look like? Maybe even something that could ship with gitoxide.
+* [ ] A truly awesome history rewriter which makes it easy to understand what happened while avoiding all pitfalls. Think BFG, but more awesome, if that's possible.
+* [ ] `git-tui` should learn a lot from [fossil-scm] regarding the presentation of data. Maybe [this](https://github.com/Lutetium-Vanadium/requestty/) can be used for prompts.
+* [ ] Can markdown be used as database so issue-trackers along with meta-data could just be markdown files which are mostly human-editable? Could user interfaces
+  be meta-data aware and just hide the meta-data chunks which are now editable in the GUI itself? Doing this would make conflicts easier to resolve than an `sqlite`
+  database.
+    * ~~A git-backend for `sqlite` which should allow embedding sqlite databases into git repositories, which in turn can be used for bug-trackers, wikis or other
+      features, making for a fully distributed github like experience, maybe.~~
+
+### Ideas for Spin-Offs
+
+* [ ] A system to integrate tightly with `git-lfs` to allow a multi-tier architecture so that assets can be stored in git and are accessible quickly from an intranet location
+  (for example by accessing the storage read-only over the network) while changes are pushed immediately by the server to other edge locations, like _the cloud_ or backups. Sparse checkouts along with explorer/finder integrations
+  make it convenient to only work on a small subset of files locally. Clones can contain all configuration somebody would need to work efficiently from their location,
+  and authentication for the git history as well as LFS resources make the system secure. One could imagine encryption support for untrusted locations in _the cloud_
+  even though more research would have to be done to make it truly secure.
+* [ ] A [syncthing] like client/server application. This is to demonstrate how lower-level crates can be combined into custom applications that use
+  only part of git's technology to achieve their very own thing. Watch out for big file support, multi-device cross-syncing, the possibility for
+  untrusted destinations using full-encryption, case-insensitive and sensitive filesystems, and extended file attributes as well as ignore files.
+
+[syncthing]: https://github.com/syncthing/syncthing
+[fossil-scm]: https://www.fossil-scm.org
+
 
 ## Shortcomings