diff --git a/doc/UsersGuide/source/Backgroundinfo/TechnicalOverview.rst b/doc/UsersGuide/source/Backgroundinfo/TechnicalOverview.rst index ef8a0dc42..7a7cec03b 100644 --- a/doc/UsersGuide/source/Backgroundinfo/TechnicalOverview.rst +++ b/doc/UsersGuide/source/Backgroundinfo/TechnicalOverview.rst @@ -51,7 +51,7 @@ It is maintained by EMC and DTC with developments and contributions from the :te The HAFS repository only hosts major feature branches (e.g., ``feature/hafs_nesting``) that require active group collaborations. Individual developers can work on feature branches in their personal HAFS forks. -.. figure:: https://raw.githubusercontent.com/wiki/hafs-community/HAFS/docs_images/hafs_branching_diagram.png +.. figure:: https://github.com/hafs-community/HAFS/wiki/docs_images/hafs_branching_diagram.png :width: 50 % :alt: Example HAFS Branching Diagram @@ -65,7 +65,7 @@ HAFS Directory Structure The following shows the names of the files and directories in the ``HAFS`` repository. -.. figure:: https://raw.githubusercontent.com/wiki/hafs-community/HAFS/docs_images/hafs_directory_structure.png +.. figure:: https://github.com/hafs-community/HAFS/wiki/docs_images/hafs_directory_structure.png :width: 50 % :alt: HAFS directory names and explanations (updated 06/29/2023) @@ -78,7 +78,7 @@ HAFS Submodules HAFS contains the following subcomponents: -.. figure:: https://raw.githubusercontent.com/wiki/hafs-community/HAFS/docs_images/hafs_submodules.png +.. figure:: https://github.com/hafs-community/HAFS/wiki/docs_images/hafs_submodules.png :width: 75 % :alt: HAFS Subcomponents/Submodules (updated 11/02/2021) @@ -88,6 +88,6 @@ HAFS contains the following subcomponents: HAFS Workflow Schematic ======================== -.. figure:: https://raw.githubusercontent.com/wiki/hafs-community/HAFS/docs_images/hafs_workflow_schematic.png +.. figure:: https://github.com/hafs-community/HAFS/wiki/docs_images/hafs_workflow_schematic.png :width: 75 % :alt: HAFS Workflow Schematic diff --git a/doc/UsersGuide/source/BuildingRunningTesting/GitHubBasicSteps.rst b/doc/UsersGuide/source/BuildingRunningTesting/GitHubBasicSteps.rst deleted file mode 100644 index 2a493571e..000000000 --- a/doc/UsersGuide/source/BuildingRunningTesting/GitHubBasicSteps.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. _BasicSteps: - -************************************************************ -Introduction to Working with the HAFS Repository in GitHub -************************************************************ - -(Please see the :ref:`Prerequisites` before beginning.) - -General steps to add new developments to the HAFS GitHub repository: - -#. Fork the HAFS repository and clone the forked repository locally. -#. Create a feature branch from the ``develop`` branch to add new developments. - - a. Add developments. - b. Complete testing. - c. Commit changes into the local branch and push the local branch to your personal fork. - -#. Submit a Pull Request (PR) to request a code review and merge new developments with the authoritative HAFS repository. - -================================================================= -Fork the HAFS Repository and Clone the Forked Repository Locally -================================================================= - -Users need a GitHub account to work with the HAFS repository. Instructions for creating an account are available `on GitHub `__ and via the `Earth Prediction Innovation Center website `__. - -#. Navigate to https://github.com/hafs-community/HAFS. Locate and click on the "fork" button towards the top right of the page. Users can create a fork by selecting the default settings; more advanced users may opt to alter the defaults. - - .. figure:: https://github.com/hafs-community/HAFS/wiki/docs_images/ForkHAFS.png - :width: 90% - :alt: Yellow box highlights the "fork" button toward the top right of the page. - -#. Clone the newly created HAFS fork, which will copy the repository onto the user's local system. - - .. code-block:: console - - git clone --recursive https://USERNAME@github.com/USERNAME/HAFS.git - - Users should replace ``USERNAME`` with their GitHub username in the command above. - - .. hint:: See `GitHub forking projects `__ - -==================================================== -Create a Feature Branch from the ``develop`` Branch -==================================================== - -#. Check out the ``develop`` branch: - - .. code-block:: console - - git checkout develop - -#. Create a new branch from the ``develop`` branch: - - .. code-block:: console - - git checkout -b feature/mybranch - -#. Update the submodules: - - *If there are changes for the URLs of the submodules, run this command to update the remote versions of the submodules* - - .. code-block:: console - - git submodule sync --recursive - - *Note: every time after you clone a git repository or check out a new branch, if submodule changes are expected, you need to update the submodules properly by* - - .. code-block:: console - - git submodule update --init --recursive - -#. Make modifications and commit changes locally: - - .. code-block:: console - - vi NewCodeFile - git add NewCodeFile - git commit -m “Add newcode description” - -#. Push changes to your GitHub HAFS fork: - - .. code-block:: console - - git push origin feature/mybranch - -========================================================================== -Submit a Pull Request for Inclusion into the Authoritative HAFS Repository -========================================================================== - -To propose changes for inclusion into the authoritative HAFS repository, developers need to create a pull request. - -#. Navigate to https://github.com/hafs-community/HAFS/pulls and click on *New pull request*. -#. Click on *Compare across forks*. - a. Set the base repository to *hafs-community/HAFS* and the base branch to ``develop``. - b. Set the head repository to *YOUR_GITHUB_USERNAME/HAFS* and the compare branch to ``feature/mybranch``. -#. Add a descriptive title and short description in the text boxes describing the changes. -#. Click on *Create pull request*. diff --git a/doc/UsersGuide/source/BuildingRunningTesting/HAFSCodeContributionGuidelines.rst b/doc/UsersGuide/source/BuildingRunningTesting/HAFSCodeContributionGuidelines.rst deleted file mode 100644 index ab7f6e317..000000000 --- a/doc/UsersGuide/source/BuildingRunningTesting/HAFSCodeContributionGuidelines.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _HAFSCodeContributionGuidelines: - -*********************************************** -UFS Repository Code Management Guidance (Draft) -*********************************************** - - -Repository -========== - -- Authoritative repositories are read-only for users. -- Branches are protected, i.e., changes can only be made through merging pull requests, not by pushing (including admins). -- All the UFS app develop branches are pointing to subcomponents’ official branches for development at different revisions. The subcomponent branch should not be a temporary branch in a user’s or developer group’s personal fork. -- No personal installed software including libraries or code are allowed in the UFS application code. No personal directory will be used in the UFS application. -- A simple and clear commit message is required when merging a pull request. (see here for standard log format) - -Forking -------- - -- For new development users will create a fork from the repositories, pull requests will be made from the branch in developers’ fork. -- When a fork is created, all the branches in the parent repository are copied automatically. It is suggested that users keep the develop branch and the branches that they are interested in and ignore the rest branches entirely or delete them -- It is suggested that users create their own feature branch from the development branch (e.g. develop or master branch) in the authoritative (or official) repository. Basically, Users can add remote upstream to the authoritative repository, check out upstream develop/master branch and then create a new feature branch from upstream develop/master branch. - -Branching ---------- - -- It is suggested that users create their own feature branch in their fork. -- Users’ develop/feature branches in user’s fork should be sync-ed with authoritative (or official) repositories periodically. -- When development work is done, users will sync their feature branch with the latest develop/master branch in the authoritative repository, run regression tests and make a pull request to the authoritative (or official) repository. -- It is suggested to delete the feature branch in users’ personal fork when the code changes are merged into an authoritative repository. -- For new development work, users will sync their development with an authoritative repository and start from step 1. - -Tagging/Versioning ------------------- - -- In an authoritative repository, only code managers can create production or public release branches. -- For the production branch, a suggested branch name is production/app.vxx, xx is the operational implementation version number (e.g. GFS.v16). Annotated tags will be created with names app.vxx.yy.zz (yy is feature upgrade, zz is bugfix upgrade) (e.g. GFS.v15.2.1). -- For the public release branch, suggested branch names: release/public-vxx.yy. Annotated Tags will be created with names: app.vxx.yy.zz. -- For develop branch, benchmark tags can be created as benchmark/app.vxx.yy.zz -- Code managers are encouraged to delete the old production and public release branches. Annotated tags will stay when the production/public release branches are deleted. -- It is suggested not to create a tag for every commit on the develop branch. Tags will only be created for special features/milestones. - -Pull Request ------------- - -- An issue needs to be created associated with the pull request. The issue should cover all the features in detail. -- Before making a pull request, users’ feature branch must be merged with the corresponding branch in the authoritative repository. All the conflicts must be resolved. Regression tests need to be passed on at least one supported platform. -- Users submit a pull request (PR) for code commit. -- Pull request creators will add reviewers, if needed, ask code managers to add reviewers. -- At least one reviewer with write permission needs to give approval before the code can be committed. -- If needed, developers can ask code manager(s) to run the regression test on the required platforms that users don’t have access to. -- When the PR is reviewed and no further changes are required, the PR can be put in the commit queue. -- For PRs that involve several repositories: - i) All PRs need to be cross-referenced in the description of each repository PR; and a note needs to be placed in each PR. - ii) During the code commit, all PRs need to be ready for commit. This requires that all the related commit branches are merged with the top of repositories and no other commit will be committed into each repository until the current commit is finished (repository freeze for the commit). If any of the repositories is updated, the code manager of that repository needs to notify all the related repository code managers to redo RT. - iii) The top application RTs need to be finished and RT information needs to be posted in all the related repositories before the PR can be merged in each individual repository. - -How to Write Pull Request --------------------------- - -- Pull request size: should be small -- Feature breaking: if possible, one feature for each PR.. -- Make a self-explanatory title describing what the PR does. -- Description: Details with what was changed, why it was changed, and how it was changed - -Code Commit ------------ - -- The code changes will be reviewed and approved by at least one code reviewer. -- The CI tests need to pass. -- Regression tests need to pass on all the supported platforms. All the regression test log files need to be updated. The exception is when a certain platform is under maintenance. For such a time, the regression test will be skipped on that platform. When the platform becomes available, the following PR will be tested and verified. If issues come up with the platform, then PRs will be suspended until the issue is resolved. -- At least one code manager needs to review and approve the code changes before the code is merged to the develop branch. -- Code managers will discuss the current PRs in UFS and sub-component repositories and a commit queue will be determined and put in the ufs wiki page. - -Commit Procedure ----------------- - -- For any PR created in the app or subcomponent repo (assume proper testing is done for the code updates), code managers needs to check: - - The PR template instruction is followed, required information is provided. - - The code is merged to the top of develop/master branch - - Put labels such as “documentation”, “bug”, “enhancement”, “baseline change”, “no baseline change”, “New Input Data Req’d”, “Input data change” - - Put “Tri diff --git a/doc/UsersGuide/source/BuildingRunningTesting/index.rst b/doc/UsersGuide/source/BuildingRunningTesting/index.rst index f2f5c6137..0d7a45b60 100644 --- a/doc/UsersGuide/source/BuildingRunningTesting/index.rst +++ b/doc/UsersGuide/source/BuildingRunningTesting/index.rst @@ -4,8 +4,6 @@ Building, Running, and Testing HAFS .. toctree:: :maxdepth: 3 - ExtQuickStart - GitHubBasicSteps QuickStart - RegressionTest - HAFSCodeContributionGuidelines \ No newline at end of file + ExtQuickStart + RegressionTest \ No newline at end of file diff --git a/doc/UsersGuide/source/Reference/ReferenceMaterials.rst b/doc/UsersGuide/source/Reference/ReferenceMaterials.rst index d71825f54..f10c893f9 100644 --- a/doc/UsersGuide/source/Reference/ReferenceMaterials.rst +++ b/doc/UsersGuide/source/Reference/ReferenceMaterials.rst @@ -15,8 +15,8 @@ Guidance Documents - `NCO Implementation Standards `__ - `Recommendation for Adoption of NCEP EE2 Process Document `__ * -- `Code Management of Repositories Under EMC Management Using GitFlow `__ * -- `EMC Github Repository Code Management `__ * +- `Code Management of Repositories Under EMC Management Using GitFlow `__ * +- `EMC Github Repository Code Management `__ * \* Requires NOAA email for access diff --git a/doc/UsersGuide/source/conf.py b/doc/UsersGuide/source/conf.py index 72af51263..d15c14b9b 100644 --- a/doc/UsersGuide/source/conf.py +++ b/doc/UsersGuide/source/conf.py @@ -91,7 +91,7 @@ ] linkcheck_allowed_redirects = {r"https://github\.com/hafs-community/HAFS/wiki/.*": - r"https://raw\.githubusercontent\.com/wiki/hafs-community/HAFS/.*", + r"https://raw\.githubusercontent\.com/wiki/hafs-community/HAFS/.*" } # -- Options for HTML output ------------------------------------------------- diff --git a/doc/UsersGuide/source/index.rst b/doc/UsersGuide/source/index.rst index 16b2aed71..bb62862d5 100644 --- a/doc/UsersGuide/source/index.rst +++ b/doc/UsersGuide/source/index.rst @@ -5,14 +5,8 @@ HAFS User's Guide (|version|) :numbered: :maxdepth: 3 - - - Backgroundinfo/index BuildingRunningTesting/index CustomizingTheWorkflow/index - Reference/index - - - - + ContributorsGuide/index + Reference/index \ No newline at end of file