0005-main-repository-name.adoc 3.12 KB
Newer Older
1 2
= ADR 0005: Main Repository Name
:revdate: 2017-11-18
Dan Allen's avatar
Dan Allen committed
3 4 5

== Status

Dan Allen's avatar
Dan Allen committed
Dan Allen's avatar
Dan Allen committed
7 8 9 10 11 12 13 14 15 16 17

== Context

When we began work on Antora, we knew we wanted to make the pipeline modular, but we weren't sure whether we wanted to use a dedicated repository for each software component or manage all the source code in a single repository.
To avoid occupying the repository name *antora* prematurely, we decided to play it safe and use the name *antora-direct*.

Since then, we've decided to organize the antora-direct repository as a monorepo (in the style of Lerna).
This decision was made to simplify development in the early stages, before any releases were made.
At the time of writing, the repository holds all the core parts of Antora minus the UI.
These components are organized under the [.path]_packages_ folder.

18 19
For newcomers, the role of this repository (antora-direct) is not obvious.
As a result, Antora lacks a "`home base`".
Dan Allen's avatar
Dan Allen committed
20 21 22 23 24 25 26

== Decision

Regardless of whether we decide to graduate core components out into dedicated repositories, we know there will always be some sort of foundation for the project.
That foundation can serve as the home base repository.

At the most basic level, the repository can provide a high-level overview of Antora and serve as a sign post to communicate where various parts of Antora can be found.
It can also serve as the umbrella for issues and documentation that don't fit with any one component, but rather belong to the project as a whole.
Dan Allen's avatar
Dan Allen committed
28 29
The scope of this repository may change over time, but we'd still always have a use for it.

Therefore, the decision has been made to rename the repository from *antora-direct* to *antora*.
Dan Allen's avatar
Dan Allen committed
In the time leading up to the first release, this repository will host all the code except for the UI.
Eventually, we foresee it transitioning into a gateway repository as components are depleted from it.
Dan Allen's avatar
Dan Allen committed
33 34 35

== Consequences

By naming the repository *antora*, it's going to become the repository that newcomers are likely going to click on first.
Dan Allen's avatar
Dan Allen committed
37 38 39 40 41 42 43 44 45 46 47 48
That's a good thing because it will offer an obvious place to start.

The downside is that it could give the impression that the whole of Antora is confined to this one repository.
However, other modular projects have used this naming pattern (e.g., jekyll, middleman, metalsmith) and there's no evidence that people misunderstand its purpose and overlook other parts of the ecosystem.
What we do see evidence of is newcomers being confused when the main repository is missing.

The purpose of this repository may need to evolve over time, and that may mean developers have to update their workflow and that issues have to be migrated to other repositories.
Fortunately, GitLab provides the tools to be able to handle these transitions, so we're confident we can make them smoothly.
What we don't know is whether this will break references to merge requests in the git commit log that were made before the name change, so that's a risk.

It's also possible to change the display name of the repository without changing the repository name (i.e., the repository path).
That would allow us to add a qualifier to the name (e.g., `Antora (Foundation)`) to make the role of the repository more clear.