docs: convert README to AsciiDoc
commit
61b6291docs: convert README to AsciiDoc
Reviews
No reviews of this commit yet — record a verdict below.
Start a review
README.adoc
@@ -1,0 +1,55 @@
+= `git-ents`
+Joey Carpinelli <joseph.carpinelli@icloud.com>
+
+[abstract]
+An (in-development) experimental forge with all metadata stored as Git objects.
+
+image:https://github.com/git-ents/git-ents/actions/workflows/CI.yml/badge.svg[CI, link=https://github.com/git-ents/git-ents/actions/workflows/CI.yml]
+image:https://github.com/git-ents/git-ents/actions/workflows/CD.yml/badge.svg[CD, link=https://github.com/git-ents/git-ents/actions/workflows/CD.yml]
+
+== Vision
+
+Git is far more flexible than existing forges assume.
+Large files can be fetched lazily via partial cloning and promisor remotes.
+New libraries, e.g. https://github.com/GitoxideLabs/gitoxide[Gitoxide], can provide atomic updates across multiple refs.
+Reflection in modern programming languages, such as https://facet.rs[`facet`], allows for more general object storage, diffing, and merging with a single procedural macro.
+// TODO
+
+== Values
+
+
+In a 2017 Node Summit talk, [https://youtu.be/Xhx970_JKX4?si=eZI1Sk355juRLAq8&t=105[Platform as a Reflection of Values], the following table of values is presented by Bryan Cantrill.
+He notes that these values are often in tension with one another, and engineering projects must prioritize some over others.
+In the interest of transparency (one of the values this project prioritizes!) the values this project deliberately prioritizes over all others are discussed immediately below.
+
+[%autowidth,cols="3*"]
+|===
+| Approachability | Interoperability | Robustness
+| Availability | Maintainability | Safety
+| Compatibility | Measurability | Security
+| Composability | Operability | #Simplicity#
+| Debuggability | Performance | Stability
+| Expressiveness | #Portability# | Thoroughness
+| #Extensibility# | Resiliency | #Transparency#
+| Integrity | Rigor | Velocity
+|===
+
+=== Simplicity
+
+// TODO
+
+=== Extensibility
+
+// TODO
+
+=== Portability
+
+// TODO
+
+=== Transparency
+
+// TODO
+
+== Usage
+
+_More documentation is en route!_
README.md
@@ -1,43 +1,0 @@
-# 🎁 `git-vendor`
-
-*An in-source vendoring alternative to submodules and subtrees.*
-
-<!-- rumdl-disable MD013 -->
-[](https://github.com/git-ents/git-vendor/actions/workflows/CI.yml)
-[](https://github.com/git-ents/git-vendor/actions/workflows/CD.yml)
-<!-- rumdl-enable MD013 -->
-
-> [!CAUTION]
-> This project is being refactored to improve the API, and use [Gitoxide][gitoxide] for all repository operations.
-> The last [release] is fully featured: please try that (alpha) release if you want to try the project out.
-> When the refactor is finished, this warning will be removed.
-
-[gitoxide]: https://github.com/GitoxideLabs/gitoxide
-[release]: https://github.com/git-ents/git-vendor/releases/tag/git-vendor-v1.0.0-alpha.1
-
-## About
-
-To support a more expansive usage of the Git object database — as is the goal for other projects within the [`git-ents`](https://github.com/git-ents) organization — new tooling is needed.
-This project provides a command that allows users to fetch and merge remote content.
-
-You may see the terms *porcelain* and *plumbing* used across this project.
-These are [borrowed from Git itself](https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain): porcelain refers to user-facing commands, and plumbing refers to the lower-level libraries and commands they are built on.
-
-## Crates
-
-| Crate | Description | API |
-|---|---|----|
-| [`git-vendor`](crates/git-vendor/) | An in-source vendoring alternative to submodules and subtrees. | Porcelain |
-| [`git-set-attr`](crates/git-set-attr/) | Set Git attributes programmatically. | Plumbing |
-
-## Alternatives
-
-This is not the first `git-vendor` project.
-In fact, despite being developed independently, this project was published *after* multiple other `git-vendor` projects.
-
-The [`thejoshwolfe/git-vendor`][thejoshwolfe] project appears to be near identical.
-Another project, [`brettlangdon/git-vendor`][brettlangdon], carries the same name but has slightly different goals; it additionally supports contributing changes upstream.
-Please check out each of those projects!
-
-[brettlangdon]: https://github.com/brettlangdon/git-vendor
-[thejoshwolfe]: https://github.com/thejoshwolfe/git-vendor