Doc: terminology: More precise terms #172

stagnation · 2025-09-16T13:03:51Z

No description provided.

…underlying root repo

moroten · 2025-09-18T10:04:09Z

doc/terminology.md

 CI systems like `Gerrit` allows an organization to merge code to multiple _repositories_
 atomically if all tests passes.


Gerrit is not a CI system, Zuul is. Gerrit has though the topic feature for submitting atomically over multiple repositories and Zuul can make use of that feature to implement atomic submission in a shared gating process.

moroten · 2025-09-18T10:06:56Z

doc/terminology.md

+There is generally only one such repo
+so it is often described in definite form: "the _toprepo_".
+
+It can also be checked out with _regular submodules_:


Suggested change

It can also be checked out with _regular submodules_:

A _toprepo_ can also be checked out with _regular submodules_:

moroten · 2025-09-22T11:34:08Z

doc/terminology.md

-that emulates a _monorepo_ for developer
-but still tracks code as _submodules_ with their own remote git _repositories_.
-This is created by `git-toprepo`.
+**emulated monorepo**: A client-side construct, _assembly_,


Suggested change

**emulated monorepo**: A client-side construct, _assembly_,

**git-toprepo emulated monorepo**: A client-side construct, _assembly_,

moroten · 2025-09-22T11:36:20Z

doc/terminology.md

+to _assemble_ an _emulated monorepo_ for a _toprepo_ and its _submodules_.
+this _combines_ the history of all _repositories_.


Suggested change

to _assemble_ an _emulated monorepo_ for a _toprepo_ and its _submodules_.

this _combines_ the history of all _repositories_.

to _assemble_ a _git-toprepo emulated monorepo_ for a _toprepo_ and its _submodules_.

This _combines_ the history of all _repositories_.

moroten · 2025-09-22T11:38:06Z

doc/terminology.md


-**filtered submodule**: A `git-toprepo` concept,
-a _submodule_ that has been assimilated into one combined history in the filtered _monorepo_.
+**assimilated submodule**: A `git-toprepo` concept,


I suggest "integrated" instead as I think that is an easier word to use, even if it might not be technically better than assimilated.

moroten · 2025-09-22T11:41:45Z

doc/terminology.md

 **monocommit**: A `git-toprepo` concept,
-a commit in the _emulated monorepo_ for the _toprepo_.
-May consist of multiple _commits_ in multiple _filtered submodules_.
+a commit in the _emulated monorepo_.


Suggested change

a commit in the _emulated monorepo_.

a commit in the _git-toprepo emulated monorepo_. Often referred to as just _m̀onocommit_ within the git-toprepo context.

moroten · 2025-09-22T11:42:21Z

doc/terminology.md


 **commit**: A core `git` concept.

 **monocommit**: A `git-toprepo` concept,


Suggested change

**monocommit**: A `git-toprepo` concept,

**git-toprepo emulated monocommit**: A `git-toprepo` concept,

moroten · 2025-09-22T11:45:08Z

doc/terminology.md

+and can track that as one _monocommit_
+-- one _commit_ in the _emulated monorepo_ that consists of one _commit_ in each of the two _assimilated submodules_.


Suggested change

and can track that as one _monocommit_

-- one _commit_ in the _emulated monorepo_ that consists of one _commit_ in each of the two _assimilated submodules_.

and can track that as one _monocommit_,

i.e. a single _commit_ in the _git-toprepo emulated monorepo_ that combines one _commit_ in each of the two _assimilated submodules_.

moroten · 2025-09-22T11:47:32Z

doc/terminology.md

+into an _emulated monorepo_ with a _combined_ history for code in the _toprepo_ itself and its _assimilated submodules_.

-**combined**: `git-toprepo` has _combined_ the history into an _emulated monorepo_ with combined history.
+**assimilate**: `git-toprepo` has _assimilated_ a _submodule_ into the _combined_ _emulated monorepo_ history.


Suggested change

**assimilate**: `git-toprepo` has _assimilated_ a _submodule_ into the _combined_ _emulated monorepo_ history.

**integrate**: `git-toprepo` has _integrated_ a _submodule_ into the _combined_ _emulated monorepo_ history.

moroten · 2025-09-22T11:50:09Z

doc/terminology.md

+if changes were made to the underlying _toprepo_,
+symmetric with _regular commits_ for the constituent _submodules_
+that are pushed to the _submodules_' remote git _repository_.
+


Add a line about monocommit = git-toprepo emulated monocommit.

albinvass · 2025-09-22T11:47:31Z

doc/terminology.md

+and can track that as one _monocommit_
+-- one _commit_ in the _emulated monorepo_ that consists of one _commit_ in each of the two _assimilated submodules_.
 Those are meant to be merged together
-through compatible CI systems that allow _shared gating_ between _repositories_.
+through compatible CI systems that allow _shared gating_ between the constituent _repositories_.

 **shared gating**: A CI system concept.
 CI systems like `Gerrit` allows an organization to merge code to multiple _repositories_
 atomically if all tests passes.
-This allows us to emaulate a _monorepo_ and have a shared gate.
-`Gerrit` uses [superproject subscription] for this
+This allows the shared gating of the constituent _submodules_.
+So the merged history is always compatible with an _emulated monorepo_,
+there are no race conditions between different _repository_ gates.
+`Gerrit` uses [superproject subscription] for this.


I missed this in the last pr and it's a good opportunity to fix it now.

Gerrit isn't a CI system so we should either replace Gerrit with Zuul or CI system with Code Review system / Git server. The latter seems more relevant since Gerrit is what allows us to atomically merge multiple commits across multiple repositories (Topics).

We don't need to have any tests passing, automatic tests, or a dependent queue for toprepo to work. Toprepo is still usefull without all of that.

However in the future if we want to support a code review system that does not have any support for Topics the way gerrit works then we'd need an external system that makes sure the toprepo is atomically updated after all submodule commits are merged. A CI system can potentially be responsible for that, but it doesn't have to be.

albinvass · 2025-09-22T11:50:16Z

doc/terminology.md


 [superproject subscription]: https://gerrit-review.googlesource.com/Documentation/user-submodules.html

 ### Verbs


See comment about adding a better introduction. I'm unsure what the section about Verbs are for. Are they for explaining concepts used in the code or so other documentation / concepts can refer back to this document?

I think it is useful to limit the list of verbs used in documentation and code.

albinvass · 2025-09-22T11:52:06Z

doc/terminology.md

 ## Examples

-### Initialization: The toprepo may be a monorepo
+### Initialization: expand the toprepo to an emulated monorepo


When do we use Assemble vs Expand?

albinvass · 2025-09-22T11:59:17Z

doc/terminology.md

 ```

-However when using _regular submodules_ in an _unmanaged_ _toprepo_
+However when using _regular submodules_ in an _repository_


Is this process even more complicated with nested submodules?

Yes. sure is. I forgot about that. Everything is a mess with those.

stagnation force-pushed the feature/doc-terminology-redefine-toprepo branch 5 times, most recently from eda334c to d148c3f Compare September 18, 2025 09:51

stagnation changed the title ~~Doc: terminology: redefine toprepo~~ Doc: terminology: More precise terms Sep 18, 2025

stagnation marked this pull request as ready for review September 22, 2025 09:45

stagnation added 5 commits September 22, 2025 11:46

Doc: revamp the terminology: we create the toprepo

d4f2ad6

doc: revamp the terminology: avoid rootrepo

71c8b56

doc: revamp the terminology: though there is merit to discussing the …

b9ad522

…underlying root repo

Doc: terminology: revamp to the most precise wording

028e3ac

Doc: terminology: assemble is more precis in some contexts

b8ddadf

stagnation force-pushed the feature/doc-terminology-redefine-toprepo branch from fb46f40 to b8ddadf Compare September 22, 2025 10:47

moroten reviewed Sep 22, 2025

View reviewed changes

albinvass reviewed Sep 22, 2025

View reviewed changes

frme edits

51e1d5c

moroten merged commit 99b8b82 into main Sep 23, 2025
7 of 8 checks passed

moroten deleted the feature/doc-terminology-redefine-toprepo branch September 23, 2025 14:14

		CI systems like `Gerrit` allows an organization to merge code to multiple _repositories_
		atomically if all tests passes.

	It can also be checked out with _regular submodules_:
	A _toprepo_ can also be checked out with _regular submodules_:

	emulated monorepo: A client-side construct, _assembly_,
	git-toprepo emulated monorepo: A client-side construct, _assembly_,

		to _assemble_ an _emulated monorepo_ for a _toprepo_ and its _submodules_.
		this _combines_ the history of all _repositories_.

	a commit in the _emulated monorepo_.
	a commit in the _git-toprepo emulated monorepo_. Often referred to as just _m̀onocommit_ within the git-toprepo context.


		commit: A core `git` concept.

		monocommit: A `git-toprepo` concept,

	monocommit: A `git-toprepo` concept,
	git-toprepo emulated monocommit: A `git-toprepo` concept,

		and can track that as one _monocommit_
		-- one _commit_ in the _emulated monorepo_ that consists of one _commit_ in each of the two _assimilated submodules_.

	assimilate: `git-toprepo` has _assimilated_ a _submodule_ into the _combined_ _emulated monorepo_ history.
	integrate: `git-toprepo` has _integrated_ a _submodule_ into the _combined_ _emulated monorepo_ history.


		[superproject subscription]: https://gerrit-review.googlesource.com/Documentation/user-submodules.html

		### Verbs

Doc: terminology: More precise terms #172

Doc: terminology: More precise terms #172

Uh oh!

Conversation

stagnation commented Sep 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!