Skip to content

Commit

Permalink
per #2207, various adjustments to the contributor's guide as describe…
Browse files Browse the repository at this point in the history 
…d in the issue comments to improve the clarity of the instructions
  • Loading branch information
@georgemccabe
georgemccabe committed Jul 24, 2023
1 parent cd44df3 commit 4c5277d
Show file tree
Hide file tree
Showing 2 changed files with 87 additions and 63 deletions.
35 changes: 27 additions & 8 deletions docs/Contributors_Guide/add_use_case.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -630,14 +630,19 @@ Add volume_mount_directories file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Copy the volume_mount_directories file from the develop directory into the
branch directory. Update the entry for the new tarball if the mounting point
has changed (unlikely) or add a new entry if adding a new sample data
tarfile. The format of this file generally follows
<category>:model_applications/<category>, i.e.
climate:model_applications/climate::
branch directory.

cp ${METPLUS_DATA_TARFILE_DIR}/develop/volume_mount_directories ${METPLUS_DATA_TARFILE_DIR}/${METPLUS_FEATURE_BRANCH}

**IF YOU ARE ADDING A NEW USE CASE TO AN EXISTING CATEGORY, SKIP TO THE NEXT STEP.**

If you are adding a new use case category, add a new entry to the volume mount
directories file for the new category.
Add the new entry in alphabetical order so it is easier for others to review.
The format of this file follows
**<category>**:model_applications/**<category>**, e.g.
**climate**:model_applications/**climate**.

Log out of DTC Web Server
^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -983,7 +988,11 @@ copy the feature file into the upcoming METplus version directory and the develo
Copy data from the feature directory into the next version directory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Copy files
""""""""""

**Make sure the paths are correct before copying.**
Paths may need to be adjusted.

**ONLY RUN THE COMMAND THAT IS APPROPRIATE TO THE USE CASE. READ CAREFULLY!**

Expand Down Expand Up @@ -1013,6 +1022,9 @@ After verifying the directories are correct, copy the files::

cp -r $from_directory $to_directory/

Handle existing tarfile in vX.Y
"""""""""""""""""""""""""""""""

List the tarfile for the use case category in the next release version directory::

cd ${METPLUS_DATA_TARFILE_DIR}/v${METPLUS_VERSION}
Expand All @@ -1033,14 +1045,21 @@ another METplus
version**, then simply remove the tarfile link::

unlink sample_data-${METPLUS_USE_CASE_CATEGORY}.tgz

Remove old data (if applicable).

**OR**

**CONDITION 3: IF the sample data tarfile for the category does not exist
(because it is a new use case category), continue to the next step.
Remove old data (if applicable)
"""""""""""""""""""""""""""""""

If the pull request notes mention an old directory path that should be removed,
please remove that directory. Be careful not to remove any files that are
still needed.

Create the new sample data tarfile.
Create the new sample data tarfile
""""""""""""""""""""""""""""""""""

**ONLY RUN THE COMMAND THAT IS APPROPRIATE TO THE USE CASE. READ CAREFULLY!**

Expand Down
115 changes: 60 additions & 55 deletions docs/Contributors_Guide/github_workflow.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -675,70 +675,75 @@ Open a pull request
then merge the files into the repository's develop branch.
The develop branch will be used to create a future METplus release.

* In the browser, navigate to https://github.com/<your-github-user>/METplus
replacing
<your-github-user> with the user's GitHub username and no angle brackets <>.

* Click on the green 'Compare & pull request' button.

* A web page with four grey buttons should appear:

* On the left-most button (for setting the base repository),
make sure the
'base repository:dtcenter/METplus' is selected.

* For the base button, make sure to select 'base:develop'.

* For the head repository button, make sure to select
'head repository:<your-github-user>/METplus'
with the appropriate replacement for
<your-github-user>.

* For the compare button, make sure to select
'compare:<your_feature_branch>'
where <your_feature_branch> corresponds to the feature branch
where the changes have been made (e.g. feature_777_wrapper_xyz).

* In the 'write' window, follow the directions and fill in the template.
Add any additional comments/details. When filling in the template,
be sure to "Define the PR metadata, as permissions allow.
Select: **Reviewer(s), Project(s)**, and **Milestone**". When selecting a
reviewer, internal contributors submitting pull requests should select
the appropriate reviewer(s) and let the reviewer know that the pull
request has been assigned to them. If external contributors are unsure
who to assign as a reviewer, create a post in the
`METplus GitHub Discussions Forum <https://github.com/dtcenter/METplus/discussions>`_
asking for help with the assignment of a reviewer.
* If working from a fork, navigate to
https://github.com/<github-user>/METplus where *<github-user>* is
the user's GitHub username. If working from a branch in the dtcenter
organization, navigate to https://github.com/dtcenter/METplus

* Click the 'Pull Requests' tab and click the green "New pull request" button.

* If working from a fork, a web page with four grey buttons should appear:

* On the left-most button (for setting the base repository),
make sure the 'base repository:dtcenter/METplus' is selected.

* For the base button, make sure to select 'base:develop'.

* For the head repository button, make sure to select
'head repository:<your-github-user>/METplus'
with the appropriate replacement for
<your-github-user>.

* For the compare button, make sure to select
'compare:<your_feature_branch>'
where <your_feature_branch> corresponds to the feature branch
where the changes have been made (e.g. feature_777_wrapper_xyz).

* If working from a branch in the dtcenter organization, there should be
two grey buttons.

* For the **base** button, select *develop*.
* For the **compare** button, select the feature or bugfix branch.

* In the 'write' window, follow the directions and fill in the template.
Add any additional comments/details. When filling in the template,
be sure to "Define the PR metadata, as permissions allow.
Select: **Reviewer(s), Project(s)**, and **Milestone**". When selecting a
reviewer, internal contributors submitting pull requests should select
the appropriate reviewer(s) and let the reviewer know that the pull
request has been assigned to them. If external contributors are unsure
who to assign as a reviewer, create a post in the
`METplus GitHub Discussions Forum <https://github.com/dtcenter/METplus/discussions>`_
asking for help with the assignment of a reviewer.

* When everything looks satisfactory, click on the green 'Create pull
request' button.
* When everything looks satisfactory, click on the green 'Create pull
request' button.

* Before a pull request is created, a "Project" can be selected, but there
is no option to select a cycle.
* Before a pull request is created, a "Project" can be selected, but there
is no option to select a cycle.

.. figure:: figure/1PR-before-created.png
.. figure:: figure/1PR-before-created.png

After the pull request is created, more options appear under the
"Project" section.
After the pull request is created, more options appear under the "Project" section.

.. figure:: figure/2PR-after-created.png
.. figure:: figure/2PR-after-created.png

Click the "Status" drop down and select "Review".
Click the "Status" drop down and select "Review".

.. figure:: figure/3PR-set-status.png
.. figure:: figure/3PR-set-status.png

Click on "+1 more" then under "Cycle", click "Choose an iteration" and
select the current development cycle.
Click on "+1 more" then under "Cycle", click "Choose an iteration" and
select the current development cycle.

.. figure:: figure/4PR-plus-one-set-cycle.png
.. figure:: figure/4PR-plus-one-set-cycle.png

To link the issue that correspondes to the pull request, click on the
gear next to "Development," type the issue number, then select the issue
that is displayed.
To link the issue that corresponds to the pull request, click on the
gear next to "Development," type the issue number, then select the issue
that is displayed.

* An authorized METplus developer will accept the pull request (if
everything meets acceptance criteria) and merge the code into the remote
repository's develop branch.
* An authorized METplus developer will accept the pull request (if
everything meets acceptance criteria) and merge the code into the remote
repository's develop branch.

Approve a pull request using a browser
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -756,8 +761,8 @@ sub-tasks to be complete, then it may be best to wait to create a pull request
until the other sub-tasks are also complete.


Creating a pull request
^^^^^^^^^^^^^^^^^^^^^^^
Reviewing a pull request
^^^^^^^^^^^^^^^^^^^^^^^^

1. Click on the “Pull requests” tab in the GitHub repository and
click on the assigned pull request.
Expand Down

0 comments on commit 4c5277d

Please sign in to comment.