For maintainers#

See also

GitHub Burndown is a handy visualization of the longevity of issues over time.

Name a project#

A product name should be:

  • Unique within OCP

    e.g. having two ‘scoping methodologies’ is confusing

  • Easy to spell and pronounce

    e.g. Shwowp became Buyosphere because no one could spell ‘Shwowp’
    e.g. an unpronounceable acronym
  • Memorable

  • Not competing with another relevant or prominent thing

  • Not generic unless only one thing fits the description

    e.g. ocdsdata became OCDS Kingfisher
    e.g. there will only ever be one OCDS Extension Registry
  • Not cryptic

    i.e. several hops of translation and analogy

  • Not grossly offensive to relevant stakeholders

Furthermore, if the product is specific to OCDS, its full name should be prefixed with ‘OCDS’.

Onboard consultants or Start a project#

  1. Create new repositories, as needed by the consultants

  2. Run the fix:lint_repos and fix:protect_branches tasks, to configure the repository

  3. Create a new team named after the consultants’ organization

    Note

    Do not use outside collaborators. Individual consultants can be collected into appropriate teams, like the Standard team.

  4. From the Members tab:

    1. Invite the Project Manager

    2. Once the invitation is accepted, set their role to Maintainer

    3. Ask them to invite the rest of their team

    4. Invite OCP program managers or project management consultants, as needed

  5. From the Repositories tab:

    1. Add the new repositories

    2. Set the Permission level to “Maintain”

      Note

      If consultants need to make changes that require Admin privileges, instead, ask the consultants for instructions to make the changes yourself.

  6. If using the stefanzweifel/git-auto-commit-action action in the lint.yml workflow, like in the Django Cookiecutter template:

    1. Add the new repositories to the Robots team

    2. Set the Permission level to “Admin”

  7. Add the new repositories to pre-commit ci

  8. Add the new repositories to Coveralls

  9. Add any projects to ReadTheDocs as appropriate

  10. Use the Django Cookiecutter template, if relevant

Per the Software terms of reference (TOR) template, consultants should not have access to the production server. As such, do not add any members to the Servers team.

Warning

NEVER assign the Owner role to non-OCP staff. The Owner role has access to a private repository with multi-factor authentication backup codes. Transferring a repository does not require the Owner role.

Tip

Update and then use the org:members, org:team_members, org:team_repos and org:team_perms tasks to check the configuration.

Note

In order to protect the private deploy repositories, the base permissions for open-contracting members is None.

pre-commit.ci workaround

pre-commit.ci disallows network connections. As such, the pip-compile pre-commit hook is configured to be skipped in the ci section of the .pre-commit-config.yaml file, and is run by the lint.yml workflow, instead.

This workflow auto fixes requirements files. To do so, it uses a personal access token of the ocp-deploy user with a repo:public_repo scope. The ocp-deploy user is the only member of the Robots team. As above, this team needs to be a repository administrator to push the auto fixes to protected branches.

Offboard consultants#

If the consultants are anticipated to contribute again, set the Permission level for all repositories to “Write”. Otherwise, delete the team.

Add repository metadata#

  1. Add a description. Do not describe the project’s status (‘draft’), because people frequently forget to update repository descriptions. Describe the status in the readme instead.

  2. Add a website to the repository, if relevant: for example, a link to a deployment of the tool or to its documentation.

Protect branches#

Tip

Use the fix:protect_branches task to protect branches.

We don’t generally enable the following behaviors on protected branches for the provided reasons:

  • Require branches to be up to date before merging: While this may avoid introducing errors, it slows development in an environment in which there are many simultaneous pull requests, because each would require an extra step before merging. If the automated tests fail after merging, the error can be corrected, or the changes can be reverted.

  • Require pull request reviews before merging: While this is a best practice, it slows development as the team is not sufficiently large to staff it. It is okay, for example, for an author to self-merge a simple change. Authors may, of course, request reviews for significant changes.

If a repository needs multiple branches (like the standard and profiles), the needed branches should be protected. Otherwise, unprotected branches more than a month old should either be opened as pull requests, protected, or deleted.

See also

Branch management of the standard and profiles (including OC4IDS).

Archive a repository#

Repositories that are no longer supported should be archived.

  1. Agree whether to archive the repository. The archived repositories presently include:

  2. Scan the repository’s open issues, milestones, pull requests and non-default branches in case any can be quickly closed, merged or deleted. Counter GitHub’s recommendation, open issues and pull requests indicate the development status of a repository, and should be left open.

  3. Change the repository’s description to describe the reason for archival. If the repository has been superseded, change it to “Superseded by [owner]/[repository]” and change the URL to the new repository’s URL.

  4. Run the fix:archive_repos REPOS=repo1,repo2 task on the repository.

  5. Move the archive to the open-contracting-archive organization.

  6. Archive the repository through its settings.

  7. Run the local:badges task.