Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 14 additions & 15 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,7 @@ released together and consumed separately.

| Module | Purpose | Depends on |
|---|---|---|
| `git-core` | Hardened repositories, remote policy, commit and reference identity, results, transport, reading, cache repository, in-core writing, compare-and-swap, in-core merge, notes | - |
| `git-worktrees` | Linked working trees, commit from a working tree, working-tree status | `git-core` |
| `git-core` | Hardened repositories, remote policy, commit and reference identity, results, transport, reading, cache repository, in-core writing, compare-and-swap, in-core merge, notes; linked working trees, commit from a working tree, working-tree status (package `worktrees`) | - |
| `git-testing` | Generators and fixtures: local and in-memory repositories, a local remote | - |
| `git-store` | Repository registry, typed configuration, codec interface, outcome list and result, service interfaces with provider selection | `git-core` |

Expand All @@ -43,12 +42,12 @@ compare-and-swap: `InCoreWriter` with `TreeEdit`, `CommitMetadata` and `CommitSi
`TreeOperation` (compare-and-swap and compare-and-delete of a reference), and with in-core merge, reading and notes:
`InCoreMerger` with the sealed `MergeResult` (the merged tree, or the conflicting paths as data), `RepositoryReader`
(snapshot, path history, changed paths) and `GitNotes` (read and write a note under a caller-named notes reference,
by compare-and-swap); its tests run on the class path against the `git-testing` fixtures. `git-worktrees` exports `de.cuioss.git.document.worktrees` with the worktree part
taken over from `pm-provider-git`: `WorktreeOperations` with `JGitWorktreeOperations` (add, list and remove linked
working trees, commit from a working tree, working-tree status `WorktreeStatus`, release of a branch reservation left
by an ended process), the package-private
`LinkedWorktrees` and the `LogRecord` holder `GitWorktreesLogMessages`; its tests run on the class path against the
`git-testing` fixtures. `git-store` exports `de.cuioss.git.document.store` with the foundation of the store: the
by compare-and-swap). `git-core` also exports `de.cuioss.git.document.core.worktrees` with the worktree part taken
over from `pm-provider-git`: `WorktreeOperations` with `JGitWorktreeOperations` (add, list and remove linked working
trees, commit from a working tree, working-tree status `WorktreeStatus`, release of a branch reservation left by an
ended process) and the package-private `LinkedWorktrees`; its log messages are declared in `GitCoreLogMessages`, the
single `LogRecord` holder of `git-core`. The tests of both packages run on the class path against the `git-testing`
fixtures. `git-store` exports `de.cuioss.git.document.store` with the foundation of the store: the
closed outcome list `StoreOutcome` and the result `StoreResult` (whose outcome is a `StoreOutcome` or a non-success
Git outcome passed on as `StoreResult.PassedOn`), the codec interface `Codec`, the repository registry
`RepositoryRegistry` with `StoreRepository`, the typed configuration `StoreConfiguration` (built by
Expand All @@ -60,12 +59,12 @@ public class of a package: javac rejects exporting a package that contains only

The build guards GDR-GEN-1 (`doc/specification/general.adoc`) with the `maven-enforcer-plugin` that `cui-parent-pom`
already binds: the execution `module-layering` of the root `pom.xml` bans every reactor dependency outside the module
graph (`git-worktrees` and `git-store` each append their one edge, `git-core`), and the execution `consumer-isolation` of `git-core/pom.xml` bans every compile or runtime artifact outside the
closure a consumer of `git-core` alone receives. `DomainTermAbsenceTest` in each module (`git-core`, `git-worktrees`,
`git-testing` and `git-store`) asserts that no public type carries a domain term. `git-core` ships native-image
metadata (`reflect-config.json`, `resource-config.json` under `META-INF/native-image/de.cuioss/git-core/`, checked by
`NativeImageMetadataTest`) for the JGit translation bundle it reaches; `git-worktrees` and `git-store` ship none and
rely on that of `git-core` (GDR-NFR-4).
graph (`git-store` is the only module that appends an edge, `git-core`), and the execution `consumer-isolation` of
`git-core/pom.xml` bans every compile or runtime artifact outside the closure a consumer of `git-core` alone receives.
`DomainTermAbsenceTest` in each module (`git-core`, `git-testing` and `git-store`) asserts that no public type carries
a domain term. `git-core` ships native-image metadata (`reflect-config.json`, `resource-config.json` under
`META-INF/native-image/de.cuioss/git-core/`, checked by `NativeImageMetadataTest`) for the JGit translation bundle it
reaches, its worktrees package included; `git-store` ships none and relies on that of `git-core` (GDR-NFR-4).

## Build

Expand Down Expand Up @@ -98,7 +97,7 @@ These follow the conventions of the foundation code that moves into this reposit
the dependencies of `git-store`, `git-forms` or `git-timestamp`.
- **Never add a dependency without the owner's approval**, JGit included.
- A new module adds its allowed reactor edges to the `module-layering` rule: one `<include>` per edge of the module
graph, in its own POM (see `git-worktrees/pom.xml`).
graph, in its own POM (see `git-store/pom.xml`).
- A new compile dependency of `git-core` is added to the `consumer-isolation` rule of `git-core/pom.xml` only after the
owner's approval; until then the build fails.
- Documentation is AsciiDoc; Javadoc on every public type and method.
Expand Down
14 changes: 5 additions & 9 deletions README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,7 @@ The repository is a multi-module Maven reactor whose modules are released togeth

|`git-core`
|Hardened repositories, remote policy, identity, results, transport, reading, cache repository, in-core writing,
compare-and-swap, in-core merge, notes.

|`git-worktrees`
|Linked working trees, commit from a working tree, working-tree status. Depends on `git-core` only.
compare-and-swap, in-core merge, notes; linked working trees, commit from a working tree, working-tree status.

|`git-testing`
|Generators and fixtures: local and in-memory repositories, a local remote.
Expand All @@ -44,9 +41,9 @@ selection. Depends on `git-core` only.

`git-core` holds the repository part taken over from its first client: hardening, remote policy, identity, results,
repository operations and the cache repository, plus in-core writing, compare-and-swap reference updates, in-core
merge, reading (snapshot, path history, changed paths) and notes. `git-worktrees` holds the worktree part taken over
from the same client: adding, listing and removing linked working trees and the commit from a working tree, plus a new
working-tree status. `git-testing` holds its credential generator and its repository fixtures (see
merge, reading (snapshot, path history, changed paths) and notes. Its package `de.cuioss.git.document.core.worktrees`
holds the worktree part taken over from the same client: adding, listing and removing linked working trees and the
commit from a working tree, plus a new working-tree status. `git-testing` holds its credential generator and its repository fixtures (see
link:doc/concepts/module-structure.adoc[Module Structure] and link:doc/clients/pm-mcp-core.adoc[Client: `pm-mcp-core`]).
`git-store` holds the foundation of the document store: the registry of its repositories, the typed configuration
checked at start, the codec interface, its own outcome list and result, and the service interfaces for signing keys,
Expand All @@ -56,8 +53,7 @@ them.

The build guards the layering and the consumer closure of `git-core`: a module that declares a dependency on another module outside the module graph fails
the build, and so does a compile or runtime artifact outside the closure a consumer of `git-core` alone receives.
`git-core` ships the GraalVM native-image metadata for the JGit classes it reaches; `git-worktrees` and `git-store`
rely on it (see
`git-core` ships the GraalVM native-image metadata for the JGit classes it reaches; `git-store` relies on it (see
link:doc/specification/general.adoc[General Requirements], GDR-GEN-1 and GDR-NFR-4).

=== Maven Coordinates
Expand Down
20 changes: 9 additions & 11 deletions doc/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -117,17 +117,17 @@ xref:specification/git-core.adoc#GDR-CORE-2[GDR-CORE-2], xref:specification/git-
xref:specification/git-core.adoc#GDR-CORE-4[GDR-CORE-4], xref:specification/git-core.adoc#GDR-CORE-5[GDR-CORE-5],
xref:specification/git-core.adoc#GDR-CORE-6[GDR-CORE-6], xref:specification/git-core.adoc#GDR-CORE-7[GDR-CORE-7],
xref:specification/git-core.adoc#GDR-CORE-8[GDR-CORE-8], xref:specification/git-core.adoc#GDR-CORE-9[GDR-CORE-9],
xref:specification/git-core.adoc#GDR-CORE-10[GDR-CORE-10] and
xref:specification/git-core.adoc#GDR-CORE-11[GDR-CORE-11] of `git-core`, and
xref:specification/git-worktrees.adoc#GDR-WT-1[GDR-WT-1], xref:specification/git-worktrees.adoc#GDR-WT-2[GDR-WT-2],
xref:specification/git-worktrees.adoc#GDR-WT-3[GDR-WT-3] and xref:specification/git-worktrees.adoc#GDR-WT-4[GDR-WT-4]
of `git-worktrees`, and xref:specification/git-store.adoc#GDR-STORE-1[GDR-STORE-1] and
xref:specification/git-core.adoc#GDR-CORE-10[GDR-CORE-10], xref:specification/git-core.adoc#GDR-CORE-11[GDR-CORE-11],
xref:specification/git-core.adoc#GDR-CORE-12[GDR-CORE-12], xref:specification/git-core.adoc#GDR-CORE-13[GDR-CORE-13],
xref:specification/git-core.adoc#GDR-CORE-14[GDR-CORE-14] and
xref:specification/git-core.adoc#GDR-CORE-15[GDR-CORE-15] of `git-core`, and
xref:specification/git-store.adoc#GDR-STORE-1[GDR-STORE-1] and
xref:specification/git-store.adoc#GDR-STORE-11[GDR-STORE-11] of `git-store`, together with its configuration, its
outcome list and its service interfaces.
xref:specification/git-core.adoc#GDR-CORE-1[GDR-CORE-1] is met with one limit: the JVM-wide process start of JGit's
`SystemReader` is closed only when the embedding application installs `RefusingFS.systemReader`, the recommended
setup. For xref:specification/general.adoc#GDR-NFR-4[GDR-NFR-4], `git-core` ships its native-image metadata and
`git-worktrees` and `git-store` rely on it; this repository does not verify the requirement yet. Every other requirement is planned.
setup. For xref:specification/general.adoc#GDR-NFR-4[GDR-NFR-4], `git-core` ships its native-image metadata, covering its
worktrees package, and `git-store` relies on it; this repository does not verify the requirement yet. Every other requirement is planned.

[cols="1,3"]
|===
Expand All @@ -138,10 +138,8 @@ setup. For xref:specification/general.adoc#GDR-NFR-4[GDR-NFR-4], `git-core` ship

|xref:specification/git-core.adoc[git-core]
|Hardened repositories, remote policy, bare clone, in-core writing, compare-and-swap, merge, transport, cache
repository, reading, notes, identity

|xref:specification/git-worktrees.adoc[git-worktrees]
|Linked working trees, commit from a working tree, working-tree status, release of a branch reservation
repository, reading, notes, identity, linked working trees, commit from a working tree, working-tree status, release
of a branch reservation

|xref:specification/git-testing.adoc[git-testing]
|Repository fixtures and the credential generator
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,8 @@ The document store writes through linked working trees, like clients whose agent

*Rejected because* no tool of the document store works on files, and JGit can read linked working trees but has no
command that creates one (see xref:../concepts/storage-engine.adoc#_no_working_trees[Storage Engine, No Working
Trees]). `git-worktrees` stays available for consumers that need files.
Trees]). The working-tree operations of `git-core` (package `de.cuioss.git.document.core.worktrees`) stay available
for consumers that need files.

=== A lock per document instead of compare-and-swap

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@
:source-highlighter: highlight.js

// adr-metadata
// summary: git-document-repository is a multi-module reactor released together; the generic, hardened JGit code becomes the foundation modules git-core, git-worktrees and git-testing, shared by the document store and other clients; the aspects of the document store are modules of their own, each carrying its own third-party dependencies.
// summary: git-document-repository is a multi-module reactor released together; the generic, hardened JGit code becomes the foundation modules git-core and git-testing, shared by the document store and other clients, and the working-tree operations are a package of git-core; the aspects of the document store are modules of their own, each carrying its own third-party dependencies.
// tags: modules, layering, dependencies, release, foundation, jgit
// affects: git-core, git-worktrees, git-testing, git-store, git-forms, git-timestamp, git-directory
// affects: git-core, git-testing, git-store, git-forms, git-timestamp, git-directory
// supersedes:
// end-adr-metadata

Expand All @@ -26,8 +26,11 @@ how the code is cut into artifacts, and whether the store copies the hardened co
*The decision:* one repository, one Maven reactor, released together to Maven Central. Every module is consumed
separately:

* `git-core`, `git-worktrees`, `git-testing` -- the JGit foundation, taken over from its first client and shared by
every client, the document store included; what is specific to a client stays with that client;
* `git-core`, `git-testing` -- the JGit foundation, taken over from its first client and shared by every client, the
document store included; what is specific to a client stays with that client. The working-tree operations (linked
working trees, commit from a working tree, working-tree status) are the package
`de.cuioss.git.document.core.worktrees` of `git-core`, not a module of their own: their only edge is `git-core`,
they add no third-party dependency, and they are released together with it;
* `git-store` -- drafts, saving, signature, index, anchoring;
* `git-forms` -- schema-driven documents;
* `git-timestamp`, `git-directory` -- optional aspects.
Expand Down
Loading
Loading