Baserock/ policies

Using Baserock

Community

Background

Baserock Policies

To better establish collaboration, and provide guidance for review, the Baserock Project has established various policies.

These policies are subject to change, following review and discussion on the baserock mailing list.

Repository Deletion

Repositories on git.baserock.org shall not be deleted, in order to ensure that any mirrors of these repositories will not be orphaned. In the event that a repository is no longer an active automated mirror of an upstream source, it shall be added to the file named "stopped-lorries" stored in the master branch of the baserock/local-config/lorries.git repository.

Maintainership

If two existing committers say that someone should have commit access, and none speaks up against it within 3 days, then that person gets commit access.

The people with commit access are the current members of the 'Mergers' group on Gerrit. Every maintainer also needs an account on git.baserock.org for pushing to git.baserock.org/delta/ *repos.

Merging changes

All changes are subject to review in Gerrit as described in Contributing to Baserock.

In addition to providing comments and suggestions for improvement, reviewers are encouraged to respond to changes with an overall +1, -1 type value. The meaning of these numbers is explained in the Gerrit documentation: Code review labels

Here is a brief summary of the values:

  • -2: This must not be merged.
  • -1: I would prefer that this is not merged as is.
  • 0: I am not making any statement about this change at the moment.
  • +1: Looks good to me, but someone else must approve it.
  • +2: Looks good to me, approved.

These values should not be added together. Two +1s does not mean a +2.

Changes are only merged to the master branch once they have received a +2 and no -2.

Reviewing 'documentation-only' changes

When reviewing a documentation-only change, consider giving a +1 with "post-merge fixups" comments, rather than predicating your +1 on fixups pre-merge. You retain the option of -1ing obviously incorrect documentation or predicating a generally good change on removing fundamental wrongness.

Baserock reference system definitions

The definitions.git repository should only point to repos hosted on git.baserock.org. This should be done using 'baserock:' and 'upstream:' keyed URLs, so that organisations which mirror git.baserock.org in their own Trove will not be dependent on git.baserock.org.

To explain a bit more clearly: Morph's 'trove-host' setting will affect how the 'baserock:' and 'upstream:' keyed URLs are expanded. By default trove-host is set to git.baserock.org, so 'upstream:example' expands to git://git.baserock.org/delta/example. But if you mirror git.baserock.org locally you can set trove-host to 'my-local-trove', and the same URL will expand to git://my-local-trove/delta/example instead. This policy means that the all source code we need to build Baserock systems is under our control, and we aren't vulnerable to projects disappearing and taking their source code servers with them.

This applies to Git submodules as well: currently you will need to patch the .gitmodules file of any component that uses Git submodules, and change the URLs to 'upstream:xxx'. Morph will then expand these URLs at build-time. It is not ideal that we have to carry patches to do this, and we would welcome an improvement to Morph that allowed overriding the submodules URLs in definitions.git to avoid the need to patch things.

If you need a repository that isn't currently mirrored on git.baserock.org, please first send a patch for the lorries.git repo to add a Lorry entry that imports the repo(s) you need.

This rule doesn't apply to personal branches within definitions.git.

Stratum versions

Strata in the Baserock reference system definitions should point to a specific version of the software in question rather than HEAD or "master". This will normally be achieved by using an unpetrify-ref to refer to a tagged version and ref to the commit hash (not the tag hash) of that version.

Shell script variable names

In shell scripts, use variable_names separated by underscores. The only exceptions to this are if you are using global variables or the variable is intended to be exported. In these cases, use variable names in ALLCAPS with no underscores.

There is some experimental evidence suggesting underscores make better variable names which may be of interest.