Starting a New BCP

It is possible that a new document needs to be created for best current practices that have not yet been captured before. This requires creating a new project, importing it into Read the Docs, and configuring the project.

Creating a New Project

The Curator needs to set up a new project at gitlab.com/DNS-OARC/bcp.

The Curator needs to have owner role of the bcp subgroup.

Nagivate to https://gitlab.com/projects/new#blank_project and fill in the following:

Project name

Set to <number>-<slug>. where <number> is the next available document number and <slug> describes shortly what the document is about.

Project URL

Set to https://gitlab.com/DNS-OARC/bcp.

Project slug

Leave it as is.

Project deployment target

No deployment planned.

Project Configuration

You can uncheck “Initialize repository with a README”. There is also no need to enable SAST or Secret Detection.

Then clone the project. For example purposes, this document now assumes we are working on the project 0000-howto-bcp.

git clone git@gitlab.com:DNS-OARC/bcp/0000-howto-bcp.git

This will create a git project source directory that you can edit. Add the following files:

README.rst

A README file with a short description what the BCP is about. You can add links to the Read the Docs instance, for example.

docs/

A directory holding all the documentation in reStructuredText, the build tools, the Sphinx configuration docs/source/conf.py and the root document docs/source/index.rst. For an example of the contents see DNS-OARC/bcp/0000/howto-bcp/doc/

Then update the index.rst file to your liking.

Importing the Project into Read the Docs

The Curator needs to import the project at the Read the Docs dashboard.

1. Click the Add project button, then Configure manually.

2. Click on the Continue button, then enter the following:

   Name:

   Set to oarc-bcp-<number>.

   Repository URL:

   Set to https://gitlab.com/DNS-OARC/bcp/<number>-<slug>/.

   Default branch:

   Set to main for now.

   Language:

   Set to English.

3. When you are done, click on the Next button.

Your documentation is building. Once the build is complete, you can click on View docs to see your document is live.

Configuring the Project

You can add more information to the project by clicking on the Settings button.

The project description, homepage, and tags for example. What values should go there is unspecified at the moment.

Adding Maintainers

The Curator is by default a maintainer of the project. This person should add the document Shepherd as administrator to the GitLab and Read the Docs projects.

For GitLab, go to Project members and click on the button Invite members. You should fill in the GitLab username or email address of the role_shepherd here.

Select the role Developer. For now, don’t set the access expiration date.

For Read the Docs, go to Maintainers and click on the button Add maintainer. You should fill in the Gitlab username or email address of the role_shepherd here.

Pull request builds

Enable pull request builds by checking the box on the page Pull request builds.

Then add a webhook for it in GitLab on the page Webhooks <. Click on New webhook and fill in the following:

Name

Give it a useful name, for example “Read the Docs”.

Description

Describe what the webhook does.

URL

Go to Read the Docs Integrations and select the GitLab incoming webhook. Copy and paste the Webhook URL.

Secret token

From the GitLab incoming webhook, copy and paste the Secret.

Trigger

Select Push events (All branches), Tag push events, Merge request events, and Pipeline events.

Custom webhook template

Leave empty.

SSL verification

Check the checkbox Enable SSL verification.

Then click on Add webhook. The project should now be set up to build the documentation automatically everytime there is a change in the source.

Setting Up Email Notification

The Shepherd can set up email ntoofications by going to Notifications and click on the button Add Notification and fill in their email address.