Updating Documents
==================

Now that we have a document, it needs to stay up to date. This is the role of
the :ref:`roles_shepherd`. At some point the shepherd should assess if a new
version is required. Discussions on mailing lists, merge requests on the
repository, etc. are indicators that a document requires a new version.

If there are no changes required to the document, the only thing to do is
to update the date that the document was assessed, and bump the minor version
of the document (see :ref:`versioning`).

Otherwise, the process for getting a new version of a BCP document contains of
the following steps:

- Depending on the quantity of the changes, the work can be done on the
  ``main`` branch, or in a newly created branch.
- Per discussion topic, a GitLab isue can be created.
- Per GitLab issue, a merge request can be created that should resolve the
  issue.
- The merge request should be reviewed by the community, and once there is
  consensus the shepherd can merge the document changes. This will
  automatically trigger a new build of the "Read the Docs" page.
- At some point the changed document becomes the new version.

.. _newbranch:

A New Branch
------------

It is not set in stone whether the new work needs to be done in a separate,
newly created branch, or can be done on the ``main`` branch. Both ways have
its merits.

The :ref:`roles_shepherd` may decide to create a new branch. It should have a
meaningful name. This can be done at `New branch
<https://gitlab.com/DNS-OARC/bcp/0000-howto-bcp/-/branches/new>`__
or via the command line with:

   .. code-block:: console

      git checkout -b version-2.0
      git push -u origin version-2.0

The branch to work on should be announced to the OARC community.

.. _discussion_topics:

Discussion Topics
-----------------

There is likely going to be discussion about the BCP documents. The
:ref:`roles_shepherd` should make sure these are captured in GitLab issues.

To create a new issue, go to `Issues
<https://gitlab.com/DNS-OARC/bcp/0000-howto-bcp/-/issues>`__
and click on the ``New item`` button.

On the page fill in the following details:

   Type
       Set to ``Issue``. The other values may be assigned to have different
       types of change requests in the future.
   Title
       Set to something short but meaningful.
   Description
       Capture the discussion, what is the problem with the current version
       of the document, and what the desired outcome is.
   Assignee
       By default, assign to the :ref:`roles_shepherd`, but it can also
       be someone else (volunteering).
   Labels
       Unused for now.
   Milestone
       Unused for now.
   Dates
       Unused for now.
   Contacts
       Unused for now.

There should not be a reason to turn on confidentiality on the issue, so
leave the checkbox unchecked. Then click on the ``Create issue`` button.

Issues may be created at any time during the process of updating the document.
Issues may be reopened if after closing new matters arise. Alternatively, a new
issue may be created to cover the new considerations.

.. _merge_requests:

Merge Requests
--------------

Anyone can create a merge request. This requires a fork of the project.

Once you have your own fork, you can create new development branches and
make changes to the document. Once satisfied, you can push these branches
and request a merge.

.. _fork_project

Fork Project
````````````

To fork the project, go to the `project page
<https://gitlab.com/matje/0000-howto-bcp>`__
and click on ``Fork``. On the page, fill in the following:

    Project name
        Leave as is.
    Project URL
        Set to ``https://gitlab.com/<namespace>``, where `<namespace>` is
        your personal GitLab space.
    Project slug
        Leave as is.
    Project description
        Optional and free form.
    Branches to include
        Select ``All branches`` (because updating a document may happen in
        an other branch than ``main``).
    Visibility level
        Select ``Public``.

Then click on the ``Fork project`` button.

.. _create_working_branch

Create Working Branch
`````````````````````

Now that you have a fork of the project, you can clone the fork and create
working branches. On the commandline type:

   .. code-block:: console

      git clone git@gitlab.com:<namespace>/0000-howto-bcp.git
      git checkout -b issue-1-fix-typos version-2.0

This creates a new working branch ``issue-1-fix-typos`` targeted at the
``version-2.0`` branch.

Now you can do some work, and once satisfied, you can push the branch upstream:

   .. code-block:: console

      git push -u origin issue-1-fix-typos

Create Merge Request
````````````````````

Now that your branch is available upstream, you can create a merge request
against the project. Go to `New merge request
<https://gitlab.com/matje/0000-howto-bcp/-/merge_requests/new>`__
and set the **Source branch** to ``issue-1-fix-typos`` (following the
example above) and click on ``Compare branches and continue``.

This will fill in the **Title** and **Description** that can be adjusted.
You can add "Closes #1" to the desription if the changes resolve an issue
(in this case issue 1).

Furthermore, set the following:

    Assignee
        Set to the :ref:`Shepherd`.
    Reviewer
        Leave unassigned.
    Milestone
        Unused for now.
    Labels
        Unused for now.
    Merge can start
        Select ``Anytime``.
    Merge options
        Leave "Delete source branch when merge request is accepted" checked.
        Leave "Squash commits when merge request is accepted" unchecked.
    Contribution
        Leave this checkbox checked.

Then click on ``Create merge request``. Your changes are now ready for review.

.. _reviewing:

Reviewing
---------

Anyone can review the changes. Discussions should happen on the merge request.

Changes can be made and should be made as fixup commits, so it is clear what
has changed after the initial merge request. A fixup commit can be made with

    .. code-block:: console

       git commit --fixup <commit>

Once the reviewers are satisfied with all the changes, they should push the
``Approve`` button. This gives an idea on consensus, the more approvals the
more clear it is for the shepherd that the changes are accepted by the
community.

Before merging, all the fixup commits should be squashed into the right commit.
This is done with a rebase:

    .. code-block:: console

       git rebase -i --autosquash

The :ref:`role_shepherd` should make sure the changes are reviewed (there
are one or more approvals), and that there is no disagreement on the issue
(there are no open comments on the merge request and corresponding issue).

If that all is true, the shepherd may merge the request. The corresponding
issue is automatically closed if the description contained "Closes #<issue>"
with `<issue>` being the issue number.

If there is no work left to be done, it is time to create a new version of
the document.

.. _versioning:

Versioning
----------

A document should be assessed at least once a year. It could be that the
assessment leads to no change. If a document does lead to a new change, the
document version should be updated. Add the following text to the note in
``index.rst`.

    Version
        The new version. Bump the patch level (rightmost number) by one if
        there are no document changes (but the metadata). Otherwise bump
        the major version (leftmost number) by one.
    Shepherd
        The :ref:`roles_shepherd` fills in their name.
    Latest assessment
        The date when the new version is created (likely today), in
        `YYYY-MM-DD` format.

For example:

    **Version**: 0.1.1

    **Shepherd**: Matthijs Mekking

    **Latest assessment**: 2026-01-20

Now this change can be committed, tagged, and pushed upstream.

   .. code-block:: console

      git add index.rst
      git commit -m "Set version to 0.1.1"
      git tag -a 0.1.1 -m 'version 0.1.1'
      git push -u --tags origin

Minor versions
``````````````

Minor version numbers are currently unused, but can be added if there are
minimal changes to the document.