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 <https://readsthedocs.com/>`__,
and configuring the project.

.. _new_project

Creating a New Project
----------------------

The :ref:`roles_curator` needs to set up a new project at
`gitlab.com/DNS-OARC/bcp <https://gitlab.com/DNS-OARC/bcp>`__.

The :ref:`roles_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`.

   .. code-block:: console

      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/
      <https://gitlab.com/DNS-OARC/bcp/0000-howto-bcp/-/tree/main/docs>`__

Then update the `index.rst` file to your liking.

.. _import_into_readthedocs

Importing the Project into Read the Docs
----------------------------------------

The :ref:`roles_curator` needs to import the project at the
`Read the Docs dashboard <https://app.readthedocs.org/dashboard/>`__.

#. Click the ``Add project`` button, then ``Configure manually``.

#. 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``.

#. 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:

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 :ref:`roles_curator` is by default a maintainer of the project. This person
should add the document :ref:`roles_shepherd` as administrator to the GitLab
and Read the Docs projects.

For GitLab, go to `Project members
<https://gitlab.com/DNS-OARC/bcp/0000-howto-bcp/-/project_members>`__ and
click on the button ``Invite members``. You should fill in the GitLab username
or email address of the :ref:`role_shepherd` here.

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

For Read the Docs, go to `Maintainers
<https://app.readthedocs.org/dashboard/oarc-bcp-0000/users/>`__ and click on the
button ``Add maintainer``. You should fill in the Gitlab username or email
address of the :ref:`role_shepherd` here.

Pull request builds
`````````````````````````````

Enable pull request builds by checking the box on the page `Pull request builds
<https://app.readthedocs.org/dashboard/oarc-bcp-0000/pull-requests/>`__.

Setting Up Email Notification
`````````````````````````````

The :ref:`roles_shepherd` can set up email ntoofications by going to
`Notifications
<https://app.readthedocs.org/dashboard/oarc-bcp-0000/notifications/>`__
and click on the button ``Add Notification`` and fill in their email address.