Guide: Creating a new GitHub repository

Is this necessary?

Before creating a new tool or repository to openactive, it's important to ask the question:

• Is this repository going to be maintained as part of the the OpenActive Infrastructure? Should it be?

• Does it help everyone in the community, rather than serve the need of one specific organisation?

If not, it might be more relevant to create a repository in openactive-contrib

Naming convention

All OpenActive repositories conform to the following naming convention, to ensure that they do not clash with other terms in the OpenActive namespace.

• At least two words

• Separated by hyphens

• If creating a vocabulary, note the specific naming convention.

GitHub repository settings

In order to ensure that GitHub Actions can make changes to branches, such as pushing to master, we need to use the "OpenActive" GitHub App whenever an access token is required with permissions greater than the default GITHUB_TOKEN. The OpenActive GitHub App is configured to "bypass" the branch rulesets in all repositories, which ensures that it can make changes without being constrained by the these rules (which primarily exist to prevent user error).

All GitHub repositories within OpenActive should by default include:

• Turn off GitHub Features: "Wikis", "Sponsorships", "Discussions", "Projects"

• Turn on GitHub Features: "Issues", "Preserve this repository"

• Pull Requests should only "Allow squash merge", to ensure a clean commit history without merge commits. The default commit message should be "Pull Request Title".

• "Allow merge commits" and "Allow rebase merging" should be unticked.

• "Automatically delete head branches" should be enabled

• "Allow auto-merge" should be enabled

• The "master"/"main" branch should have a Branch Ruleset that includes the following:

  • Name the Branch Ruleset as "Default branch protection"

  • Enforcement status: Active

  • Bypass list

    • Add bypass for the "OpenActive" App

      • Note the app requires access to the repo before it will appear in this list

  • Branch targeting criteria: "include default branch"

  • Restrict deletions

  • Require linear history

  • Require a pull request before merging

    • Require approvals: 1

    • Allowed Merge Methods: Squash only

  • Require status checks to pass

    • Require branches to be up to date before merging

    • Include required checks that cover the appropriate test GitHub Actions

  • Block force pushes

• Consider which OpenActive Organization secrets need to be exposed to this repository and expose the minimum.