From 0fad04f7c132c60f65c5975de8a94cca4a921929 Mon Sep 17 00:00:00 2001 From: jennyhickson Date: Tue, 15 Jul 2025 14:54:59 +0100 Subject: [PATCH 1/4] add definitions box --- source/WorkingPractices/branches.rst | 88 --------- source/WorkingPractices/common_keywords.rst | 49 ----- source/WorkingPractices/tickets.rst | 186 ------------------ source/WorkingPractices/working_practices.rst | 14 +- 4 files changed, 12 insertions(+), 325 deletions(-) delete mode 100644 source/WorkingPractices/branches.rst delete mode 100644 source/WorkingPractices/common_keywords.rst delete mode 100644 source/WorkingPractices/tickets.rst diff --git a/source/WorkingPractices/branches.rst b/source/WorkingPractices/branches.rst deleted file mode 100644 index d49b5817..00000000 --- a/source/WorkingPractices/branches.rst +++ /dev/null @@ -1,88 +0,0 @@ -Create & Checkout a Branch -========================== -The source management tool is `FCM `_, which is based on subversion -but with some subtle differences, both of which are very different from git. - -**LFRic Core** branches are usually taken from the head of trunk to allow all changes -to build on each other. - -**UM, LFRic Apps, JULES and UKCA** branches are taken from the last released revision. -Head of Trunk branches are accepted for picking up and building on a -specific development that has already been committed since the last revision. - -Branch Management using FCM ---------------------------- - -To create a branch using fcm, use the following command, replacing ``NNN`` with your ticket number, -``project`` with your project identifier, ``XX.Y`` with your -version number (e.g. ``11.1``) and ``branchname`` with a suitable branch name (not including -the version number): - -.. code-block:: - - fcm bc --ticket=NNN --type=dev branchname fcm:project.x_tr@vnXX.Y - -.. note:: - **Project Identifiers** - Most project identifiers are the same as the name of the project, including: - - * UM: um - * UM Docs: um_doc - * LFRic Apps: lfric_apps - * LFRic Core: lfric - * JULES: jules - * UKCA: ukca - -.. tip:: - - Choose a sensible, descriptive and preferably unique name for your branch, while being relatively - short (less than 50 characters). - - Branches named ``vn1.0_fix_bug`` or ``vn12.3_my_test`` aren't especially helpful. - - If you have to create a new branch at a different version to include the same feature, it is a good - idea to keep the branch names the same; that way it is easier for someone to know that the branches - are related in the trac repository. - -Upon running the ``fcm bc`` command, the user is provided with a text editor window in which to make -comments about their change. The first comment is usually one indicating that a branch has been -created and a brief summary of what it will do: - -.. code-block:: - - #NNN: Creates a branch to - -Where ``NNN`` should be replaced by the ticket number. Saving and exiting the text editor -will produce a message in the terminal asking whether the user really wants to create the branch. -Enter ``y`` to continue. - -.. _checkout: - -Checking out a branch to a working copy ---------------------------------------- - -To check out your branch immediately after creating it, look for the line in the terminal -which starts with ``[info] Created: https://code.metoffice.gov.uk/``. Copy the full URL and -it can then be checked out with - -.. code-block:: - - fcm co - -Alternatively, or to check out your branch at a later date, use the following command: - -.. code-block:: - - fcm co fcm:project.x_br/dev/mosrsuser/vnXX.Y_branchname - -Here, in addition to the project and version numbers, the user should include their Met Office -SRS user name (e.g. ``joebloggs``) in place of ``mosrsuser``. - -.. Note:: - - FCM allows the creation of branches in one of three types: development (abbreviated to dev), - test and package (abbreviated to pkg). Branches which contain code intended for the - trunk of a project should be of the dev type. Package branches are intended for grouping - multiple code changes together into a single package, while the use of test branches will - be covered later in :ref:`testing`. - diff --git a/source/WorkingPractices/common_keywords.rst b/source/WorkingPractices/common_keywords.rst deleted file mode 100644 index f9ac3193..00000000 --- a/source/WorkingPractices/common_keywords.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _keywords: - -Commonly-Used Keywords -====================== - -The following table lists some common keywords you may sometimes -see: - -+--------------+------------------------------------------------+-----------------------------------------------+ -| Keyword | Usage | Notes | -+==============+================================================+===============================================+ -| collab: | Indicates that the ticket has been authored | Use form ``collab:`` | -| | by someone who is not 100% employed | e.g. ``collab:niwa``, ``collab:oxford`` | -| | by the Met Office | | -+--------------+------------------------------------------------+-----------------------------------------------+ -| blocks: | Code change is blocking the numbered ticket | e.g. blocks:#1234 | -| | from going on to the project's trunk | Not used by LFRic Core as they have a | -| | | "blocked by" item in their ticket options. | -+--------------+------------------------------------------------+-----------------------------------------------+ -| blockedby: | Code change is blocked by the numbered ticket | e.g. blockedby:#6789 | -| | from going on to the project's trunk | Not used by LFRic Core as they have a | -| | | "blocked by" item in their ticket options. | -+--------------+------------------------------------------------+-----------------------------------------------+ -| kgo | Indicates the change requires new kgo | Includes when a new job is added to the | -| | installing (change in answers); | project's rose stem suite | -| | See :ref:`KGO `. | | -+--------------+------------------------------------------------+-----------------------------------------------+ -| macro | Indicates the change includes an | | -| | upgrade macro | | -+--------------+------------------------------------------------+-----------------------------------------------+ -| doc | Indicates that the change includes | | -| | documentation updates | | -+--------------+------------------------------------------------+-----------------------------------------------+ -| SR: | Denotes person who will SciTech | Optional for reviews outside of the SSD | -| | review the change | team; Added later in development | -+--------------+------------------------------------------------+-----------------------------------------------+ -| CR: | Denotes person who will CodeSys | Added when the reviewer is assigned. | -| | review the change | | -+--------------+------------------------------------------------+-----------------------------------------------+ -| linked:um | Indicates that the change has a linked | | -| | ticket with the code base specified by | | -| linked:jules | the keyword. These are just examples - all | | -| | linked repositories should be included. | | -| linked:core | | | -| | | | -| linked:apps | | | -| | | | -| linked:ukca | | | -+--------------+------------------------------------------------+-----------------------------------------------+ diff --git a/source/WorkingPractices/tickets.rst b/source/WorkingPractices/tickets.rst deleted file mode 100644 index f892a1ee..00000000 --- a/source/WorkingPractices/tickets.rst +++ /dev/null @@ -1,186 +0,0 @@ -.. _ticket: - -Create a Ticket -=============== -Every change requires an associated ticket. This helps the developer -organise and document their work and the reviewers to perform and -document their tasks. It also provides a permanent record to refer -back to. - -#. Log in to the Science Repository Service with your username and password. -#. Navigate to the project you wish to create a ticket in. -#. Click the ``New ticket`` button in the ribbon which appears at the top right of the Trac webpage. - -.. image:: images/new_ticket.png - :class: dark-light - -The ticket information can then be filled in. A description of each item in the ticket is as follows: - -Summary -------- - -This should be a single-line, top-level summary of your change. Do not make -it too generic (e.g. ``fix bug``) as this doesn't help identify your ticket -from potentially thousands in the Trac system. Try and use something more -descriptive (e.g. ``Fix out-of-bounds issue in subroutine radar_wavelength``). - - -Description ------------ - -This box allows for a more verbose description of what the issue is and -supporting information. The description box can be modified during the -development process to include additional information about the change. - -.. tip:: - If your ticket follows-on from an earlier development, you can mention - this in the description by linking the ticket e.g. - ``Further changes following #1234``. - - Tickets in other repositories can also be linked by including their - repository name and a colon before the ticket number, e.g. ``um:#1``, - ``lfric:#23``, - -Type ----- - -Most repositories have a set of standard types, e.g.: - - * Defect (e.g. bug fix or issue) - * Enhancement (e.g. new scientific functionality) - * Optimisation (to use less resources) - * Task (for any other code change; e.g. delete unused code). - -You should choose whichever type is most appropriate to your code change. - -**LFRic Core** has a number of different types. Either choose the most appropriate -based on your change or seek guidance from a member of the Core Capability Development -team or an experienced LFRic developer. - -Milestone ---------- - -This is used to indicate the release or version of the model your change will -be included at. These vary between projects, but it's common to choose either -a milestone for the next release, or a milestone without a deadline date. - -.. tip:: - Most projects also have a ``hopefully`` or ``somewhen`` milestone for changes - which don't yet have a milestone assigned. If you are developing - a change, it's a good idea to set the milestone to this while - doing the early development and especially if you are unsure as to which - release cycle your change will make. This prevents you from being chased - by the SSD team when the release deadline draws near. - -All tickets for a particular milestone are visible either from the Roadmap -feature in Trac or via a custom query in View Tickets. - -Cc --- - -**Optional:** Enter the usernames of others who wish to receive email -updates with the ticket status (e.g. co-developers). If in doubt, it's -best to leave this box blank. - -.. tip:: - Use the cc box sparingly as the Trac system does generate an email - every time the ticket is updated. Trac will also send an email to - **anyone** who has edited a ticket. - - Therefore if someone includes your name in the cc box, editing - the ticket yourself to take your name out of the cc list will mean - you get the same amount of email from Trac as you have 'touched' the - ticket. - -Priority (LFRic Core/JULES/UKCA/CASIM) --------------------------------------- - -This is a list of options to show how important that the change is -committed to your project, including: - -* blocker (LFRic only) -* critical -* major -* normal (not used in LFRic) -* minor -* trivial - -Again, the developer should choose whichever they feel is the most -appropriate setting. - -.. tip:: - It's best to use the higher priority categories sparingly and with - prior consultation (e.g. for an urgent bug fix). If in doubt, just - select ``normal`` or ``minor``. - - -Severity (UM/LFRic Apps/SOCRATES) ---------------------------------- - -The UM, LFRic Apps and SOCRATES have a ticket severity menu instead of a priority -menu. These are as follows: - -* **Wholesale**: A code change which alters a huge number of files. Use only with prior consultation of the SSD team. -* **Significant**: Any code change which touches more than one repository, updates KGO or changes both source code and metadata. -* **Minor**: A change which touches source code *or* metadata, **but not both**. -* **Trivial**: A small change of only a couple of lines of code. - -.. note:: - Trivial tickets do not need a SciTech review; they should be simple - and small enough that a CodeSys reviewer can easily understand them without - any major scientific or technical changes. - -Keywords --------- - -**Optional:** Keywords are generally used to identify specific aspects -for certain tickets and for managing the way tickets are added to a -project's trunk. - -A list of :ref:`keywords` is available. - -.. toctree:: - :hidden: - - common_keywords - -.. tip:: - Usually there's no particular need to add keywords which are synonyms - for items in the title or description. However, project keywords may - be useful for some people. - - If in doubt, it's best to leave the keywords box blank initially, as - keywords can always be added at a later date. - -Component (all repositories except LFRic Apps, JULES and UKCA) --------------------------------------------------------------- - -Components vary significantly between different modelling systems. Please -review the list of options and select the one most appropriate to your change, -seeking advice from an experienced developer if you are unsure. - -For the UM, selecting ``general`` is probably the best option if your change does -not fit into any of the existing categories. - -Owner ------ -Set yourself to be the owner of the ticket. Alternatively, with prior -agreement, you can set it to be any user of the SRS. - -.. warning:: - Do not leave the Owner box as ````. This will often result in - your ticket becoming lost in the system! It's always best to assign it - to yourself, even if you know that someone else will eventually make - the change. - -Associated With (LFRic Core only) ---------------------------------- -This box is used to link branches and wiki page templates as the ticket is -developed. It is safe to leave it blank when first creating the ticket. - -Blocked by (LFRic Core only) ----------------------------- -This box can be used to list other tickets which block this change. This -allows the SSD team to prioritise the commit order of the tickets on to -the trunk. Non-LFric Core tickets can specify `blocks` and `blockedby` in the -keywords box. diff --git a/source/WorkingPractices/working_practices.rst b/source/WorkingPractices/working_practices.rst index 3633ace6..12995e28 100644 --- a/source/WorkingPractices/working_practices.rst +++ b/source/WorkingPractices/working_practices.rst @@ -59,14 +59,24 @@ the process is very comparable to that of the other repositories too. To get started with the ``gh`` cli, see the `gh quickstart guide `_ +.. admonition:: Definitions + + ``Upstream``: the primary or parent repository, owned by the MetOffice github organisation. Only maintainers have write access to this repository. + + ``Fork`` or ``Downstream``: a copy of the upstream repository, owned by the developer. This is where development branches are created and worked on. + + ``Remote``: the version of the upstream or forked repository that is hosted by Github. + + ``Clone``: a local copy of the upstream or forked repository. + Simulation Systems github repositories are setup with at least 2 protected branches, ``stable`` and ``main`` (with the potential for additional version branches to be added). * ``stable`` - This branch is the default github branch and generally remains unchanged throughout a release cycle. It is the stable point from which new branches should be cut. Only new releases and small hotfixes to a release will be merged back into this branch. * ``main`` - This branch is where new development pull requests will be merged. It will never be behind the ``stable`` branch, but will regularly be ahead. All pull requests should be set to target this branch (more on this later) and a CI check will fail if it isn't. -All general development for Simulation Systems Github repos will take place on forks of that repository. It is the responsibility of the developer to maintain their own fork. See :ref:`forking` for advice on forking. +All general development for Simulation Systems Github repositories will take place on forks of that repository. It is the responsibility of the developer to maintain their own fork. See :ref:`forking` for advice on forking. -The development cycle can be seen below. ``Upstream`` (blue) refers to parent repository, owned by the MetOffice github organisation. ``Downstream`` (grey) refers to the forked repository, owned by the developer. +The development cycle can be seen below. .. image:: images/git-dev-strategy.svg :class: dark-light From 67cb07b9cd10089ac4b0f76030c8cb74732f9cee Mon Sep 17 00:00:00 2001 From: Jenny Hickson <61183013+jennyhickson@users.noreply.github.com> Date: Tue, 15 Jul 2025 15:27:25 +0100 Subject: [PATCH 2/4] Update source/WorkingPractices/working_practices.rst Co-authored-by: James Bruten <109733895+james-bruten-mo@users.noreply.github.com> --- source/WorkingPractices/working_practices.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/WorkingPractices/working_practices.rst b/source/WorkingPractices/working_practices.rst index 12995e28..75b434d1 100644 --- a/source/WorkingPractices/working_practices.rst +++ b/source/WorkingPractices/working_practices.rst @@ -65,7 +65,7 @@ the process is very comparable to that of the other repositories too. ``Fork`` or ``Downstream``: a copy of the upstream repository, owned by the developer. This is where development branches are created and worked on. - ``Remote``: the version of the upstream or forked repository that is hosted by Github. + ``Remote``: the version of either the upstream or the forked repository that is hosted by Github. ``Clone``: a local copy of the upstream or forked repository. From 720aa6b5983f55c9afe7828b7f4b9251c66d3c64 Mon Sep 17 00:00:00 2001 From: Jenny Hickson <61183013+jennyhickson@users.noreply.github.com> Date: Tue, 15 Jul 2025 15:27:32 +0100 Subject: [PATCH 3/4] Update source/WorkingPractices/working_practices.rst Co-authored-by: James Bruten <109733895+james-bruten-mo@users.noreply.github.com> --- source/WorkingPractices/working_practices.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/WorkingPractices/working_practices.rst b/source/WorkingPractices/working_practices.rst index 75b434d1..2b426bf0 100644 --- a/source/WorkingPractices/working_practices.rst +++ b/source/WorkingPractices/working_practices.rst @@ -67,7 +67,7 @@ the process is very comparable to that of the other repositories too. ``Remote``: the version of either the upstream or the forked repository that is hosted by Github. - ``Clone``: a local copy of the upstream or forked repository. + ``Clone``: a local copy of either the upstream or the forked repository. Simulation Systems github repositories are setup with at least 2 protected branches, ``stable`` and ``main`` (with the potential for additional version branches to be added). From bd8d4959216bb1d230fd5ffafa332cd7afa23321 Mon Sep 17 00:00:00 2001 From: jennyhickson Date: Tue, 15 Jul 2025 15:31:58 +0100 Subject: [PATCH 4/4] add link to gh glossary! --- source/WorkingPractices/working_practices.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/WorkingPractices/working_practices.rst b/source/WorkingPractices/working_practices.rst index 2b426bf0..597cdfdb 100644 --- a/source/WorkingPractices/working_practices.rst +++ b/source/WorkingPractices/working_practices.rst @@ -69,6 +69,8 @@ the process is very comparable to that of the other repositories too. ``Clone``: a local copy of either the upstream or the forked repository. + Further definitions can be found in the `GitHub Glossary `_. + Simulation Systems github repositories are setup with at least 2 protected branches, ``stable`` and ``main`` (with the potential for additional version branches to be added). * ``stable`` - This branch is the default github branch and generally remains unchanged throughout a release cycle. It is the stable point from which new branches should be cut. Only new releases and small hotfixes to a release will be merged back into this branch.