update default main

source/Reviewers/howtocommit.rst

@@ -12,7 +12,7 @@ The process for committing a ticket follows this sequence with details for each
     Before You Start:
       * Is anyone else committing?
 
-        * `Trunk Status`_ is used to coordinate trunk commits all projects.
+        * `Main Status`_ is used to coordinate trunk commits all projects.
         * Simple, not conflicting commits can be done in parallel if reviewers all agree.
         * Changes with KGO or Macros usually require sole access to the trunk.
       * Check how many commits have happened today. Suggested limit per day, per repository is 4.
@@ -51,7 +51,7 @@ are more complicated conflicts ask the developer to solve them themselves. If
 there are conflicts in versions.py then see the details in the macro section
 below.
 
-Then checkout the up to date branch, eg.
+Then switch to the up to date branch, eg.
 
 .. code-block::
 
@@ -130,7 +130,7 @@ rose-stem app then you will need to upgrade the test-suite.
 
             .. note::
 
-                All LFRic Core tickets with macros are expected to be linked with LFRic Apps, though they may not have required an LFRic Apps development branch (although an Apps ticket should be provided). This is fine - if there is no LFRic Apps branch just checkout the LFRic Apps trunk. Then run the apply_macros script as described above and this will share the upgrade macro across both LFRic Apps and LFRic Core as needed.
+                All LFRic Core tickets with macros are expected to be linked with LFRic Apps, though they may not have required an LFRic Apps development branch (although an Apps ticket should be provided). This is fine - if there is no LFRic Apps branch just checkout the LFRic Apps main. Then run the apply_macros script as described above and this will share the upgrade macro across both LFRic Apps and LFRic Core as needed.
 
     .. important::
 
@@ -283,7 +283,7 @@ are no clashes with what else has gone on trunk.
         .. code-block:: RST
 
             git pull
-            git checkout <branch name>
+            git switch <branch name>
             cd <path_to>/user_guide/doc
             conda activate jules-user-guide
             make html
@@ -622,4 +622,4 @@ If something is broken:
     * You can then access other machines as the admin user via ``ssh -Y
       <HOSTNAME>``.
 
-.. _Trunk Status: https://code.metoffice.gov.uk/trac/lfric_apps/wiki/TrunkStatus
+.. _Main Status: https://code.metoffice.gov.uk/trac/lfric_apps/wiki/TrunkStatus

source/WorkingPractices/forking.rst

@@ -72,6 +72,8 @@ Most work to maintain a fork involves syncing it with the upstream repository. S
         .. image:: images/gh_screenshots/sync_fork_dark.png
             :class: only-dark border
 
+        The synced branch will still only exist in the remote repository. If you require them in a local clone make sure to ``fetch`` or ``pull`` the repository.
+
     .. tab-item:: gh cli
 
         Run the following command, substituting for the downstream fork owner and repo name. Without the ``-b`` option, only the default branch will be synced. You may want to sync both ``stable`` and ``main``, particularly at a release.
@@ -80,9 +82,7 @@ Most work to maintain a fork involves syncing it with the upstream repository. S
 
             gh repo sync <OWNER>/<REPO> -b <BRANCH>
 
-        .. tip::
-
-            When using the gh cli to sync forks, remember that it won't pull the changes to local clone, this needs to be done manually.
+        The synced branch will still only exist in the remote repository. If you require them in a local clone make sure to ``fetch`` or ``pull`` the repository.
 
     .. tab-item:: git commands
 
@@ -94,8 +94,8 @@ Most work to maintain a fork involves syncing it with the upstream repository. S
 
         .. code-block::
 
-            # Checkout the desired branch
-            git checkout main
+            # Change to the desired branch
+            git switch main
 
             # Merge in changes from the upstream
             git merge upstream/main

source/WorkingPractices/gh_dev_init.rst

@@ -41,7 +41,11 @@ There is no requirement to open an issue before making a pull request, as long a
 Clone the Repository
 --------------------
 
-A clone is a local copy of a repository - you can have a local clone of either an upstream repository or a fork. A clone will have an active branch which will initially be the default branch of the repository. All other branches in the repository can be accessed using the ``checkout`` command (see below). For general development, you should now get a clone of your fork.
+A clone is a local copy of a repository - you can have a local clone of either
+an upstream repository or a fork. A clone will have an active branch which will
+initially be the default branch of the repository. All other branches in the
+repository can be accessed using the ``switch`` command (see below). For
+general development, you should now get a clone of your fork.
 
 .. tip::
 
@@ -121,14 +125,14 @@ To create a branch and switch to it from the command line, the syntax is,
 
         .. code-block::
 
-            git branch <branch_name> <source_branch>
-            git checkout <branch_name>
+            # parent_branch will default to the current branch if not provided
+            # switch will automatically change to the newly created branch
+            git switch -c <branch_name> [<parent_branch>]
 
-            # or
-
-            git checkout <source_branch>
-            git checkout -b <branch_name>
+            # Or
 
+            git branch <branch_name> <parent_branch>
+            git switch <branch_name>
 
 Developing a Change
 -------------------
@@ -155,7 +159,7 @@ And then commit the change,
 
     In git you do not need to commit all modified files unlike in svn/fcm. It is also possible to only commit certain parts of a modified file. For more information see the relevant man page, ``man git add``.
 
-Finally, you may want to push any commits stored in your local clone.
+Finally, you may want to push any commits stored in your local clone back to the remote source.
 
 .. code-block::
 

source/WorkingPractices/git_extras.rst

@@ -25,8 +25,8 @@ It is possible to set another repository as a remote source using the syntax,
 
     git remote add <name> <url>
 
-The URL for the upstream can be found from the Code button on github (see
-:ref:`Cloning a Repository <clone_repo>`).
+The URL for the desired repository can be found from the Code button on github
+(see :ref:`Cloning a Repository <clone_repo>`).
 
 .. tip::
 

source/WorkingPractices/pull_requests.rst

@@ -41,9 +41,8 @@ You have 4 options to consider.
   merged into. It will be the upstream repository you forked from.
 * ``base`` - This is the branch in the ``base repository`` where the pull
   request will be merged into. It will default to the repositories default
-  branch. However, most pull requests to simulation systems repositories will be
-  targetting ``main``, so make sure to change that here (it can be done later if
-  forgotten).
+  branch which for Simulation Systems repositories will be ``main`` which is as
+  desired.
 * ``head repository`` - This is the repository where the pull request changes
   are coming from - it will be your forked repository.
 * ``compare`` - This is the branch in the ``head repository`` containing
@@ -57,7 +56,9 @@ You have 4 options to consider.
 
 Fill out the rest of the pull request by giving an appropriate title and
 supplying a description. The description box will contain a pull request
-template to fill out. Ensure that the option to allow edits by maintainers box
+template to fill out - this can be completed now, or edited later before passing to review.
+
+Finally, ensure that the option to allow edits by maintainers
 is selected (see :ref:`reviewer_edits` for details).
 
 .. image:: images/gh_screenshots/maintainer_edit_light.png
@@ -66,16 +67,16 @@ is selected (see :ref:`reviewer_edits` for details).
 .. image:: images/gh_screenshots/maintainer_edit_dark.png
     :class: only-dark border
 
+Once you are happy with the pull request details open the pull request.
+Initially you can choose to do this in draft mode, to allow you time to do any
+final fixes based on continuous integration. If you use draft mode mark the
+pull request as ``ready for review`` once you are satisfied.
+
 .. tip::
 
     It is possible to `link your pull request with an issue
     <https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue>`_
 
-
-Once you are happy with the pull request details open the pull request.
-Initially you can choose to do this in draft mode, to allow you time to do any
-final fixes based on continuous integration. If you use draft mode mark the pull request as ``ready for review`` once you are satisfied.
-
 Continuous Integration
 ----------------------
 
@@ -147,9 +148,10 @@ conflicts. Alternatively, you can do this from a terminal using git.
         .. code-block::
 
             cd /path/to/clone
-            git checkout <desired-branch>
+            git switch <desired-branch>
 
-        Ensure that the upstream repository is available as a remote source. See :ref:`setting git remote sources <git_remote>` for more details.
+        Ensure that the upstream repository is available as a remote source.
+        See :ref:`setting git remote sources <git_remote>` for more details.
 
         Then fetch and merge in the upstream main,
 

source/WorkingPractices/working_practices.rst

@@ -24,15 +24,13 @@ Development Cycle Overview
 The general features of the development cycle are similar to those found in
 other scientific software. However, the details are tuned to meet the needs of
 the community as a whole. A key feature is the use of versions as a way of
-periodically bringing everything together. Although many elements of Continuous
-Integration and related approaches to software management can be found, the
-nature of LFRic and UM development makes following these impractical.
+periodically bringing everything together.
 
 The release cycle follows a semi-regular cadence, balancing flexibility to
 facilitate high priority goals against stability for the broader developer pool.
 Each release will consist of a development window spanning from release of the
 previous version to a pre-announced code review deadline. Following this,
-submissions will be processed culminating in the release of the next release.
+submissions will be processed culminating in the next release.
 From time to time, some or all parts of a repository may be subject to an agreed
 closed release to facilitate an intense or disruptive development.
 
@@ -63,30 +61,45 @@ the process is very comparable to that of the other repositories too.
 
     ``Clone``: a local copy of either the upstream or the forked repository.
 
-    ``Fork`` or ``Downstream``: a copy of the upstream repository, owned by the developer. This is where development branches are created and worked on.
+    ``Fork`` or ``Downstream``: a copy of the upstream repository, owned by the
+    developer. This is where development branches are created and worked on.
 
     ``Origin``: the default name for the remote source of a cloned repository.
 
-    ``Remote``: the version of either the upstream or the forked repository that is hosted by Github.
+    ``Remote``: the version of either the upstream or the forked repository
+    that is hosted by Github.
 
-    ``Upstream``: the primary or parent repository, owned by the MetOffice github organisation. Only maintainers have write access to this repository.
+    ``Upstream``: the primary or parent repository, owned by the MetOffice
+    github organisation. Only code reviewers are able to directly interact with
+    this repository, rather than being required to use forks.
 
 
-    Further definitions can be found in the `GitHub Glossary <https://docs.github.com/en/get-started/learning-about-github/github-glossary>`_.
+    Further definitions can be found in the
+    `GitHub Glossary <https://docs.github.com/en/get-started/learning-about-github/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).
+Simulation Systems github repositories are setup with at least 2 protected
+branches, ``main`` and ``stable`` (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.
+* ``main`` - This is the default github branch and is the branch that new
+  development pull requests should target. It will never be behind ``stable``
+  branch, but will regularly be ahead.
+* ``stable`` - This branch represents the codebase at a version release and
+   will generally remain unchanged throughout a release cycle. New branches
+   should be made from this branch (or from a release tag.) Only new releases
+   and small hotfixes to a release will be merged back into this branch.
 
-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.
+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.
 
 .. image:: images/git-dev-strategy.svg
     :class: dark-light
 
-For detailed explanation of these steps, see pages on :ref:`gh_dev_init` and :ref:`pull_requests`.
+For detailed explanation of these steps, see pages on :ref:`gh_dev_init` and
+:ref:`pull_requests`.
 
 Before You Start
 ----------------