Gerrit Code Owners Directory Approval Lab
=========================================

This kit targets Gerrit 3.14.2 and the Code Owners stable-3.14 build listed in
VERSION.env. Replace every example domain, account, and group UUID before use.

1. Verify the kit
-----------------

  sha256sum -c SHA256SUMS
  shellcheck scripts/install-code-owners.sh

2. Back up Gerrit
-----------------

Back up the Gerrit etc, plugins, and git data directories. Confirm that the
backup can be read before changing the running service.

3. Install the plugin with global enforcement disabled
------------------------------------------------------

Run from the directory containing the Gerrit compose.yaml:

  ALLOWED_EMAIL_DOMAIN=example.internal \
    bash /path/to/files/scripts/install-code-owners.sh

Expected result:

  Code Owners installed with global enforcement disabled: 3d7f275e...

Verify the plugin in Gerrit Administration > Plugins. The plugin must show
Enabled. Check the startup log for load failures.

4. Prepare project safety configuration
----------------------------------------

Fetch refs/meta/config from the review project. Copy these files into that
checkout:

  project/project.config
  project/code-owners.bootstrap.config -> code-owners.config
  project/groups.example -> groups

Replace the example Administrators UUID in groups. Merge the existing project
configuration instead of overwriting unrelated labels or access rules.

Push the configuration through review:

  git push origin HEAD:refs/for/refs/meta/config

Review and submit the change. Code Owners remains disabled for this project,
but OWNERS validation is forced for refs/heads/*.

5. Add the OWNERS baseline before enabling the gate
---------------------------------------------------

Copy the example OWNERS files into the source branch:

  project/OWNERS          -> OWNERS
  project/frontend/OWNERS -> frontend/OWNERS
  project/backend/OWNERS  -> backend/OWNERS

Replace all example emails with resolvable Gerrit account emails. The
find-owners backend accepts account emails in OWNERS files; it does not accept
Gerrit group names there.

Commit and upload the baseline:

  git push origin HEAD:refs/for/main

The push output should report that code owner config files were validated with
no issues. Review and submit the change while the gate is still disabled.

6. Enable Code Owners for the project
-------------------------------------

In the refs/meta/config checkout, replace code-owners.config with:

  project/code-owners.config

Upload, review, and submit the config change. The final file keeps
refs/meta/config excluded so project configuration cannot lock itself.

7. Verify a cross-directory change
----------------------------------

Create one change that modifies both files:

  frontend/README.md
  backend/README.md

Upload it to refs/for/main. A frontend owner approval must not approve the
backend file because both directory OWNERS files contain set noparent.

Check the change status endpoint while the change is blocked:

  curl -fsS \
    'https://review.example.internal/a/changes/PROJECT~CHANGE/revisions/current/code_owners.status'

Expected state:

  frontend/README.md: APPROVED
  backend/README.md: INSUFFICIENT_REVIEWERS

After the backend owner votes Code-Review+1, both files should be APPROVED and
the Code-Owners submit requirement should be SATISFIED.

8. Recovery
-----------

The first recovery path is a reviewed refs/meta/config change that sets:

  [codeOwners]
    disabled = true

The project config branch remains excluded from Code Owners, so this path does
not require an owner approval.

If the plugin prevents Gerrit from starting, restore the saved gerrit.config
and remove code-owners.jar from the mounted plugins directory while Gerrit is
stopped, then start Gerrit and verify the HTTP version endpoint.

9. Scope boundary
-----------------

Code Owners is an approval gate. It does not hide files or prevent Git fetch.
Use separate Gerrit projects when repositories require different read or push
permissions.