From 4176bcef519d2a30b951fb35e54189f421229c2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Proust?= Date: Wed, 11 Oct 2023 08:11:49 +0200 Subject: [PATCH 1/4] Docs: update guidelines to allow MR refs in comments --- docs/developer/guidelines.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/developer/guidelines.rst b/docs/developer/guidelines.rst index 567efb492065..c729b2dff4fc 100644 --- a/docs/developer/guidelines.rst +++ b/docs/developer/guidelines.rst @@ -55,7 +55,7 @@ When the place of the future evolution is known in advance (e.g. a given functio .. code-block:: ocaml - (* TODO: + (* TODO: *) @@ -65,12 +65,13 @@ If the evolution is needed to fix some code that does *not* fully implement its Thus, the difference between ``TODO`` and ``FIXME`` tags is a semantic one, reflecting the full/partial implementation of the specification. Consequently, when the specification evolves to become more demanding, some ``TODO`` tags corresponding to *potential* evolutions may have to be recasted as ``FIXME`` tags, corresponding to *required* evolutions. -Note that the reference to an existing issue on the first line is mandatory, to facilitate searches of evolutions corresponding to given issues, and might be checked automatically by the :ref:`Merge-Request Bot `. +Note that the reference to an existing issue or merge request on the first line is mandatory, to facilitate searches of evolutions corresponding to given issues, and might be checked automatically by the :ref:`Merge-Request Bot `. The reference to an issue may be one of: - a URL such as ``https://gitlab.com/tezos/tezos/-/issues/1377`` -- a GitLab notation such as ``#123`` (implicitly under ``tezos/tezos``), ``michelson-reference#123`` (implicitly under ``tezos/michelson-reference``), +- a GitLab notation for an issue such as ``#123`` (implicitly under ``tezos/tezos``), ``michelson-reference#123`` (implicitly under ``tezos/michelson-reference``), or ``oxheadalpha/merbocop#123`` (fully qualified). +- a GitLab notation for a merge request such as ``!10990``. License ------- -- GitLab From 1bd9c4e919e2a1535f908d5e0b6ba500dd3f331b Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 3 Jan 2024 17:05:56 +0000 Subject: [PATCH 2/4] doc: mention possible automated checks of todo/fixme tags --- docs/developer/guidelines.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/developer/guidelines.rst b/docs/developer/guidelines.rst index c729b2dff4fc..bd2abd916891 100644 --- a/docs/developer/guidelines.rst +++ b/docs/developer/guidelines.rst @@ -65,7 +65,8 @@ If the evolution is needed to fix some code that does *not* fully implement its Thus, the difference between ``TODO`` and ``FIXME`` tags is a semantic one, reflecting the full/partial implementation of the specification. Consequently, when the specification evolves to become more demanding, some ``TODO`` tags corresponding to *potential* evolutions may have to be recasted as ``FIXME`` tags, corresponding to *required* evolutions. -Note that the reference to an existing issue or merge request on the first line is mandatory, to facilitate searches of evolutions corresponding to given issues, and might be checked automatically by the :ref:`Merge-Request Bot `. +Note that the reference to an existing issue or MR on the first line is mandatory, to facilitate searches of specific evolutions. +These tags might be checked automatically by the :ref:`Merge-Request Bot `, e.g. to signal tags that refer to non-existent issues or MRs, to closed issues, or to already merged MRs. The reference to an issue may be one of: - a URL such as ``https://gitlab.com/tezos/tezos/-/issues/1377`` -- GitLab From 805e2693651ea0aa36ee7775e8579ff364101313 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 3 Jan 2024 17:07:27 +0000 Subject: [PATCH 3/4] doc: only FIXME tags may refer to MRs --- docs/developer/guidelines.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer/guidelines.rst b/docs/developer/guidelines.rst index bd2abd916891..2cf6fbdbe4ff 100644 --- a/docs/developer/guidelines.rst +++ b/docs/developer/guidelines.rst @@ -55,7 +55,7 @@ When the place of the future evolution is known in advance (e.g. a given functio .. code-block:: ocaml - (* TODO: + (* TODO: *) -- GitLab From e57f66e68687fb32076f6c4506f7ab5200a3d4f1 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 3 Jan 2024 17:08:24 +0000 Subject: [PATCH 4/4] doc: explain common cases for referring to an MR instead of an issue --- docs/developer/guidelines.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/developer/guidelines.rst b/docs/developer/guidelines.rst index 2cf6fbdbe4ff..1c4ceaef60fa 100644 --- a/docs/developer/guidelines.rst +++ b/docs/developer/guidelines.rst @@ -65,6 +65,14 @@ If the evolution is needed to fix some code that does *not* fully implement its Thus, the difference between ``TODO`` and ``FIXME`` tags is a semantic one, reflecting the full/partial implementation of the specification. Consequently, when the specification evolves to become more demanding, some ``TODO`` tags corresponding to *potential* evolutions may have to be recasted as ``FIXME`` tags, corresponding to *required* evolutions. +Another consequence of the fact that FIXME tags indicate an already-specified remaining work, they can point to a merge request (MR) instead of an issue, especially when the remaining work has already been started. This may correspond to at least the following familiar scenarios: + +1. You are making a list of small-sized MRs to fix one big issue, and in one MR you want to point the reviewers to other MRs already started. +2. While working on some MR, you notice a problem with your code, by which it derives from the specification. But you already have one approval for the current MR and you don't want to invalidate it by adding a significant chunk of code. So you fix the problem in a separate MR from the one you are working on. + +In the above cases, it would be possible to create a new (sub-)issue, and reference it in the code (and also in the MR). But that would add a level of indirection, both for the person doing the work and for the person reviewing the work. +Therefore, in such cases, it can be more convenient to refer to an MR directly. + Note that the reference to an existing issue or MR on the first line is mandatory, to facilitate searches of specific evolutions. These tags might be checked automatically by the :ref:`Merge-Request Bot `, e.g. to signal tags that refer to non-existent issues or MRs, to closed issues, or to already merged MRs. The reference to an issue may be one of: -- GitLab