From b490e86c095fa47b94162fa9878da2222c35881b Mon Sep 17 00:00:00 2001 From: johnhg Date: Thu, 1 Dec 2022 15:23:13 -0700 Subject: [PATCH] Feature #1885 gh_projects (#1973) Co-authored-by: George McCabe <23407799+georgemccabe@users.noreply.github.com> --- docs/Contributors_Guide/github_workflow.rst | 269 ++++++++++++++++++ ...finalize_release_on_github_development.rst | 7 +- .../finalize_release_on_github_official.rst | 8 +- .../update_release_notes_bugfix.rst | 14 +- .../update_release_notes_development.rst | 18 +- .../update_release_notes_official.rst | 18 +- 6 files changed, 291 insertions(+), 43 deletions(-) diff --git a/docs/Contributors_Guide/github_workflow.rst b/docs/Contributors_Guide/github_workflow.rst index 3744be95b6..fe6496042c 100644 --- a/docs/Contributors_Guide/github_workflow.rst +++ b/docs/Contributors_Guide/github_workflow.rst @@ -22,6 +22,275 @@ develop branch. When a release candidate for METplus has been determined, then the develop branch is used to create a main_vx.y release of METplus, which includes data tarballs for use in running use cases. +.. _wo-development-project: + +GitHub Projects to manage development +------------------------------------- + +Software development for official METplus releases is organized into development cycles. +While the length a development cycle can vary widely, they are nominally 6 weeks long. +GitHub issues and pull requests assigned to each cycle are either completed during the +time window for that cycle or reassigned to a future development cycle. + + +Each development cycle culminates in the creation of a software release. The +:ref:`releaseCycleStages` section describes the various types of software releases +(development, official, or bugfix). Each development cycle culminates in a beta release, +a release candidate, or the official release. Generally, a **beta** development cycle results +in a **beta** development release while an **rc** development cycle results in an **rc** +development release. + + +The METplus team uses GitHub projects to manage these development cycles as well as the support +of official releases. In earlier versions, each development cycle was managed by an individual +GitHub project but more recent versions use a single GitHub project to manage all of the +development cycles. Listed below are instructions for creating a single GitHub project to +manage development toward a new official release. Note that sufficient permissions in GitHub +are required to perform the following steps. + + +1. Create a **New project**. + + - From the `DTCenter GitHub Projects `_ + page, select the **New project** button. + + - In the **Select a template** popup window, select the **Project templates: Feature** + option, and click the **Create** button. + +2. Update the project **Settings**. + + - Click on the three dots to the right of the project name to see **More options** + and select **Settings**. Modify these settings as follows. + + - Project name: The default project name is **@UserNames's feature**. Rename it as + **{METplus Component}-{Target Version Number} Development** (e.g. **METplus-5.1.0 Development**). + + - Add a description: Add **Development toward {METplus Component} version {Target Version Number}.** + + - README: Add additional details as needed to the **README** section. Projects managing development + for multiple repositories, such as METplus-Analysis, should list the target version number for + each repository. + + - Scroll down to the **Danger zone** and change **Visibilty** from its default value of **Private** + to **Public**. + + - Select **Manage access** on the left hand navigation bar. + + - By default, the project creator has **Admin** access. + + - Add **Admin** access for any user with that level of access to any one + of the repositories managed by this project. + + - Add **Write** access for the **METplus** group. + + - Locate the **Custom fields** section in the left hand navigation bar + + - Select **Status** and retain the default list of options, but delete the + **New** option by clicking the **X** to its right. + + - Select **Iteration** and modify the **Field name** to be **Cycle**. Delete any existing cycles. + Under **More options** select a **Start on** date and set the default **Duration** as 6 weeks. + Click the **Add** and **Add iteration** buttons to create 5 cycles, each with the default duration + of 6 weeks. Modify the cycle names to be **Beta1**, **Beta2**, and so on. Click **Save changes**. + + - Select **Estimate** and click the three dots to the right and **Delete field**. + + - Click the back arrow to return to the project page. + +3. Update the project **Workflows**. + + - Click on the three dots to the right of the project name to see **More options** + and select **Workflows**. Modify these settings as follows. + + - Enable the **Item added to project** workflow and set the status to **Backlog**. + + - Enable the **Item reopened** workflow and set the status to **In progress**. + + - Enable the **Item closed** workflow and set the status to **Done**. + + - Enable the **Pull request merged** workflow and set the status to **Done**. + + - Leave all other workflows disabled. + + - Click the back arrow to return to the project page. + +4. Create project **Views**. + + - Each view appears as a tab on the project page. Create a new view as described below. + + - Select the **+ New view** option. + + - Click on the view name to modify it, rename it as **All Cycles**, and hit **Enter**. + + - Click on the down arrow and, under **Configuration**, select the **Fields** option. Enable + the options for **Title**, **Repository**, **Assignees**, **Cycle**, **Status**, + **Linked Pull Request**, and **Reviewers**. Drag and drop the items to reorder them as listed above. + + - In the resulting view, click the three dots in the **Status** column. Select the **Sort descending** + and **Group by values** options. + + - The blue dot on the down arrow for this tab indicates that there are unsaved changes. + Select the **Save changes** option. + + - Click on the down arrow and select **Duplicate View**. Do this 8 times and name/refine these views as follows. + + - View name **All Required** shows all items labelled as *REQUIRED* for the development or official release. + Click on the 3 horizontal bars and define the filtering criteria as + **label:"required: FOR OFFICIAL RELEASE","required: FOR DEVELOPMENT RELEASE" is:open**. Click **Save Changes**. + + - View name **Beta1** to **Beta5** shows items for each individual development cycle. + Click on the 3 horizontal bars and define the filtering criteria as **cycle:Beta1**, **cycle:Beta2**, + and so on. Click **Save Changes**. + + - View name **Closed Issues** shows issues that have been closed across all development cycles. + Click on the 3 horizontal bars and define the filtering criteria as **is:closed is:issue**. + Click on the 3 dots in the **Cycle** column and select **Group by values**. Click **Save Changes**. + + - View name **High/Blocker Not Required** shows all items labelled as *HIGH* or *BLOCKER* priority but + not marked as required for the development or official release. + Click on the 3 horizontal bars and define the filtering criteria as + **is:open label:"priority: high","priority: blocker" -label:"required: FOR DEVELOPMENT RELEASE" -label:"required: FOR OFFICIAL RELEASE"**. + Click **Save Changes**. + + - Delete any other views created by default by clicking the down arrow next to the view name and + selecting **Delete view**. + +5. Refine the project settings, development cycle dates, and views, as needed, based on the preferences + of the development team. + +6. Link the new project to each repository. + + - Navigate to the project page for each repository managed by this project + (e.g. `METplus Projects `_). + + - Click the **Link a project** button and find/select this newly created project. + +.. _wo-support-project: + +GitHub Projects to manage support +--------------------------------- + +Support for coordinated METplus releases is managed using a *single* GitHub project +for all components. Bugfix issues and the corresponding pull request fixes are added +to that support project. Each fix is assigned to the current bugfix milestone of +the corresponding source code repository. + + +The :ref:`releaseCycleStages` section describes the various types of software releases +(development, official, or bugfix). The GitHub support project contains issues and +pull requests that apply only to bugfix releases. + + +Listed below are instructions for creating a GitHub project to manage support after an +official coordinated METplus release. Note that sufficient permissions in GitHub are +required to perform the following steps. + + +1. Create a **New project**. + + - From the `DTCenter GitHub Projects `_ + page, select the **New project** button. + + - In the **Select a template** popup window, select the **Project templates: Feature** + option, and click the **Create** button. + +2. Update the project **Settings**. + + - Click on the three dots to the right of the project name to see **More options** + and select **Settings**. Modify these settings as follows. + + - Project name: The default project name is **@UserNames's feature**. Rename it as + **METplus Version X.Y Support** (e.g. **METplus Version 5.0 Support**). + + - Add a description: Add **Issues related to support for the METplus X.Y + coordinated release.** + + - README: List the X.Y version number for each METplus component contained within + the coordinated release. + + - Scroll down to the **Danger zone** and change **Visibilty** from its default value + of **Private** to **Public**. + + - Select **Manage access** on the left hand navigation bar. + + - By default, the project creator has **Admin** access. + + - Add **Admin** access for at least 2 other users with that level of access on one + of the METplus component repositories. + + - Add **Write** access for the **METplus** group. + + - Locate the **Custom fields** section in the left hand navigation bar + + - Select **Status** and retain the default list of options, but delete the + **New** option by clicking the **X** to its right. + + - For **Iteration** and **Estimate**, click the 3 dots to the right of the + **Field name** and **Delete field**. + + - Click the back arrow to return to the project page. + +3. Update the project **Workflows**. + + - Click on the three dots to the right of the project name to see **More options** + and select **Workflows**. Modify these settings as follows. + + - Enable the **Item added to project** workflow and set the status to **Backlog**. + + - Enable the **Item reopened** workflow and set the status to **In progress**. + + - Enable the **Item closed** workflow and set the status to **Done**. + + - Enable the **Pull request merged** workflow and set the status to **Done**. + + - Leave all other workflows disabled. + + - Click the back arrow to return to the project page. + +4. Create project **Views**. + + - Each view appears as a tab on the project page. Create a new view as described below. + + - Select the **+ New view** option. + + - Click on the view name to modify it, rename it as **All Milestones**, and hit **Enter**. + + - Click on the down arrow and, under **Configuration**, select the **Fields** option. Enable + the options for **Title**, **Repository**, **Assignees**, **Milestone**, **Status**, + **Linked Pull Request**, and **Reviewers**. Drag and drop the items to reorder them + as listed above. + + - In the resulting view, click the three dots in the **Milestone** column. Select the + **Sort descending** and **Group by values** options. + + - The blue dot on the down arrow for this tab indicates that there are unsaved changes. + Select the **Save changes** option. + + - Click on the down arrow and select **Duplicate View**. Name/refine this views as follows. + + - View name **Closed Issues** shows issues that have been closed across all bugfix + milestones. Click on the 3 horizontal bars and define the filtering criteria as + **is:closed is:issue**. Click on the 3 dots in the **Milestone** column and select + **Group by values**. Click **Save Changes**. + + - Delete any other views created by default by clicking the down arrow next to the view + name and selecting **Delete view**. + +5. Refine the project settings and views, as needed, based on the preferences of the support team. + +6. Link the new project to each repository. + + - Navigate to the project page for each METplus component repository: + + - `METplus `_, + `MET `_, + `METviewer `_, + `METexpress `_, + `METplotpy `_, + `METcalcpy `_, + `METdataio `_ + + - Click the **Link a project** button and find/select this newly created support project. Sequence of Events - Contributing Code -------------------------------------- diff --git a/docs/Release_Guide/release_steps/finalize_release_on_github_development.rst b/docs/Release_Guide/release_steps/finalize_release_on_github_development.rst index e33c60bc49..194b758c04 100644 --- a/docs/Release_Guide/release_steps/finalize_release_on_github_development.rst +++ b/docs/Release_Guide/release_steps/finalize_release_on_github_development.rst @@ -2,7 +2,6 @@ Finalize Release on GitHub -------------------------- * Close the GitHub issue for creating this development release. -* Edit the development project name for the current release to indicate the actual release date. -* Review the remaining development projects, and if neccessary, add new ones. -* If necessary, reassign any remaining issues from the current development project to the next one. -* Close the development project for the current release. +* Edit the date of the development cycle for the current release to indicate the actual release date. +* Review the remaining development cycles, and if neccessary, adjust dates and/or add new cycles. +* If necessary, reassign any remaining issues for the current development cycle to the next one. diff --git a/docs/Release_Guide/release_steps/finalize_release_on_github_official.rst b/docs/Release_Guide/release_steps/finalize_release_on_github_official.rst index 45123c695d..8ce6b0db5c 100644 --- a/docs/Release_Guide/release_steps/finalize_release_on_github_official.rst +++ b/docs/Release_Guide/release_steps/finalize_release_on_github_official.rst @@ -19,9 +19,13 @@ Finalize Release on GitHub * Update projects: - * Confirm that all existing development projects for the current milestone are closed. + * Close the existing development project for the current milestone. - * If necessary, create development projects for the next milestone (e.g. |projectRepo|-X.Y.Z-beta1, beta2, beta3). + * If necessary, see :ref:`wo-support-project` to create a support project for the current + METplus coordinated release. + + * If necessary, see :ref:`wo-development-project` to create a development project for the + next milestone. * Update branches: diff --git a/docs/Release_Guide/release_steps/update_release_notes_bugfix.rst b/docs/Release_Guide/release_steps/update_release_notes_bugfix.rst index 70456f029e..7fe434deae 100644 --- a/docs/Release_Guide/release_steps/update_release_notes_bugfix.rst +++ b/docs/Release_Guide/release_steps/update_release_notes_bugfix.rst @@ -6,21 +6,13 @@ release. Open the following URL in a browser: .. parsed-literal:: - https://github.com/orgs/dtcenter/projects?type=beta + https://github.com/orgs/dtcenter/projects * Click on the project that corresponds to support for the release, i.e. METplus Version X.Y Support -* Navigate to the "Closed Issues" tab. - **If this tab does not exist**, follow these instructions to create it: - - * Click on "+ New view" button on the far right side of the view tabs - * Click on "View " (where is an integer) and rename it to - "Closed Issues" - * Click on the down arrow next to the newly created view - * Click on "Search or filter this view" - * Enter the following info into the filter bar: **is:closed is:issue** - * Click on the down arrow next to the view and click "Save changes" +* Navigate to the "Closed Issues" tab. If this tab does not exist, + see :ref:`wo-support-project` to create it. * Find the closed issues with dtcenter/|projectRepo| in the Repository column that have been added since the last bugfix release for |projectRepo|. diff --git a/docs/Release_Guide/release_steps/update_release_notes_development.rst b/docs/Release_Guide/release_steps/update_release_notes_development.rst index 8cc4021a6c..72c2d1ce25 100644 --- a/docs/Release_Guide/release_steps/update_release_notes_development.rst +++ b/docs/Release_Guide/release_steps/update_release_notes_development.rst @@ -6,21 +6,13 @@ release. Open the following URL in a browser: .. parsed-literal:: - https://github.com/orgs/dtcenter/projects?type=beta + https://github.com/orgs/dtcenter/projects * Click on the project that corresponds to this release, i.e. - |projectRepo|-X.Y.Z-betaN - -* Navigate to the "Closed Issues" tab. - **If this tab does not exist**, follow these instructions to create it: - - * Click on "+ New view" button on the far right side of the view tabs - * Click on "View " (where is an integer) and rename it to - "Closed Issues" - * Click on the down arrow next to the newly created view - * Click on "Search or filter this view" - * Enter the following info into the filter bar: **is:closed is:issue** - * Click on the down arrow next to the view and click "Save changes" + |projectRepo|-X.Y.Z Development + +* Navigate to the "Closed Issues" tab. If this tab does not exist, + see :ref:`wo-development-project` to create it. * Update the release-notes.rst file found in the User's Guide directory. diff --git a/docs/Release_Guide/release_steps/update_release_notes_official.rst b/docs/Release_Guide/release_steps/update_release_notes_official.rst index 02e077b4f6..d9e39e954d 100644 --- a/docs/Release_Guide/release_steps/update_release_notes_official.rst +++ b/docs/Release_Guide/release_steps/update_release_notes_official.rst @@ -6,21 +6,13 @@ release. Open the following URL in a browser: .. parsed-literal:: - https://github.com/orgs/dtcenter/projects?type=beta + https://github.com/orgs/dtcenter/projects * Click on the project that corresponds to this release, i.e. - |projectRepo|-X.Y.Z-rcN - -* Navigate to the "Closed Issues" tab. - **If this tab does not exist**, follow these instructions to create it: - - * Click on "+ New view" button on the far right side of the view tabs - * Click on "View " (where is an integer) and rename it to - "Closed Issues" - * Click on the down arrow next to the newly created view - * Click on "Search or filter this view" - * Enter the following info into the filter bar: **is:closed is:issue** - * Click on the down arrow next to the view and click "Save changes" + |projectRepo|-X.Y.Z Development + +* Navigate to the "Closed Issues" tab. If this tab does not exist, + see :ref:`wo-development-project` to create it. * Update the release-notes.rst file found in the User's Guide directory.