Skip to content

Commit

Permalink
Simplify README - move some content to doc/
Browse files Browse the repository at this point in the history
  • Loading branch information
mbarbin committed Jul 24, 2024
1 parent b0234ca commit 80510bc
Show file tree
Hide file tree
Showing 4 changed files with 74 additions and 74 deletions.
73 changes: 0 additions & 73 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,83 +19,10 @@ Vcs's documentation is published [here](https://mbarbin.github.io/vcs).

Explore the [example](example/) directory to get a firsthand look at how Vcs works in practice.

## Architecture

The `vcs` repository contains several components:

```mermaid
stateDiagram-v2
vcs : vcs *
user : user-lib *
git_cli : git-cli
executable : executable (eio)
provider : vcs-git
runtime : eio
vcs --> user
user --> executable
git_cli --> provider
runtime --> provider
provider --> executable
```

- **vcs**: The main entry point of the library. Marked with a * to indicate no
runtime dependencies.
- **user-lib**: A placeholder in the diagram for any library that uses `Vcs`.
Also marked with a * to indicate no runtime dependencies.
- **executable**: A placeholder for a runtime component based on `user-lib` that
commits to a specific provider and concurrency model.
- **git-cli**: A IO-free library that parses the output of a `git` cli process.
- **vcs-git**: An instantiation of `Git_cli` based on an `Eio` runtime.
- **vcs-git-blocking**: An instantiation of `Git_cli` based on the OCaml `Stdlib`.

```mermaid
stateDiagram-v2
vcs : vcs *
user : user-lib *
git_cli : git-cli
executable : executable (blocking)
provider : vcs-git-blocking
runtime : stdlib
vcs --> user
user --> executable
git_cli --> provider
runtime --> provider
provider --> executable
```

## Design principles

`Vcs` is designed to be backend-agnostic and concurrency-runtime independent. It's compatible with both `Eio` and OCaml `Stdlib` runtimes. We plan to explore the feasibility of supporting [luv](https://github.com/aantron/luv) and [miou](https://github.com/robur-coop/miou) runtimes as separate future work.

The concurrency runtime must be compatible with programs written in a direct style. Runtime based on monadic concurrent models such as `Async` and `Lwt` are purposely left outside of the scope of this project.

## How It Works

`Vcs` is an interface composed of [Traits](doc/docs/design/traits.md), each providing different functionalities associated with Git interaction. The dynamic dispatch implementation of Vcs is powered by the [provider](https://github.com/mbarbin/provider) library.

## Motivation

Our goal is to create a versatile and highly compatible library that can cater to a wide range of use cases, while also fostering community engagement. We also hope to gain practical experience with the use of provider-based parametric libraries.

## Relation to ocaml-git

[ocaml-git](https://github.com/mirage/ocaml-git) is a pure OCaml implementation of the Git format and protocol. In the `Vcs` framework, an Eio compatible `ocaml-git` is a potential `provider` for the interface. We plan to create a `Vcs` provider based on `ocaml-git` in the future.

```mermaid
stateDiagram-v2
vcs : vcs *
user : user-lib *
executable : executable (eio)
ocaml_git : ocaml_git_eio
provider : ocaml-git-provider
runtime : eio
vcs --> user
user --> executable
ocaml_git --> provider
runtime --> provider
provider --> executable
```

## Acknowledgements

We extend our gratitude to the following individuals and teams, whose contributions have been great sources of inspiration for the `Vcs` project:
Expand Down
72 changes: 72 additions & 0 deletions doc/docs/design/introduction.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# Design principles

`Vcs` is designed to be backend-agnostic and concurrency-runtime independent. It's compatible with both `Eio` and OCaml `Stdlib` runtimes. We plan to explore the feasibility of supporting [luv](https://github.com/aantron/luv) and [miou](https://github.com/robur-coop/miou) runtimes as separate future work.

The concurrency runtime must be compatible with programs written in a direct style. Runtime based on monadic concurrent models such as `Async` and `Lwt` are purposely left outside of the scope of this project.

## How It Works

`Vcs` is an interface composed of [Traits](./traits.md), each providing different functionalities associated with Git interaction. The dynamic dispatch implementation of Vcs is powered by the [provider](https://github.com/mbarbin/provider) library.

## Architecture

The `vcs` repository contains several components:

```mermaid
stateDiagram-v2
vcs : vcs *
user : user-lib *
git_cli : git-cli
executable : executable (eio)
provider : vcs-git
runtime : eio
vcs --> user
user --> executable
git_cli --> provider
runtime --> provider
provider --> executable
```

- **vcs**: The main entry point of the library. Marked with a * to indicate no
runtime dependencies.
- **user-lib**: A placeholder in the diagram for any library that uses `Vcs`.
Also marked with a * to indicate no runtime dependencies.
- **executable**: A placeholder for a runtime component based on `user-lib` that
commits to a specific provider and concurrency model.
- **git-cli**: A IO-free library that parses the output of a `git` cli process.
- **vcs-git**: An instantiation of `Git_cli` based on an `Eio` runtime.
- **vcs-git-blocking**: An instantiation of `Git_cli` based on the OCaml `Stdlib`.

```mermaid
stateDiagram-v2
vcs : vcs *
user : user-lib *
git_cli : git-cli
executable : executable (blocking)
provider : vcs-git-blocking
runtime : stdlib
vcs --> user
user --> executable
git_cli --> provider
runtime --> provider
provider --> executable
```

## Relation to ocaml-git

[ocaml-git](https://github.com/mirage/ocaml-git) is a pure OCaml implementation of the Git format and protocol. In the `Vcs` framework, an Eio compatible `ocaml-git` is a potential `provider` for the interface. We plan to create a `Vcs` provider based on `ocaml-git` in the future.

```mermaid
stateDiagram-v2
vcs : vcs *
user : user-lib *
executable : executable (eio)
ocaml_git : ocaml_git_eio
provider : ocaml-git-provider
runtime : eio
vcs --> user
user --> executable
ocaml_git --> provider
runtime --> provider
provider --> executable
```
2 changes: 1 addition & 1 deletion doc/docusaurus.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ const config: Config = {
},
{
label: 'Design',
to: '/docs/design/traits/',
to: '/docs/design/introduction/',
},
{
label: 'Tests',
Expand Down
1 change: 1 addition & 0 deletions doc/sidebars.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ const sidebars: SidebarsConfig = {
type: 'category',
label: 'Design',
items: [
{ type: 'doc', id: 'design/introduction', label: 'Introduction' },
{ type: 'doc', id: 'design/traits', label: 'Traits' },
],
},
Expand Down

0 comments on commit 80510bc

Please sign in to comment.