From 563b874e2fafb68363d625b2b8d2bc3196c14031 Mon Sep 17 00:00:00 2001 From: Kelvin Date: Tue, 5 Dec 2023 16:10:36 -0700 Subject: [PATCH 1/9] Testing Grammar Check --- .github/workflows/ci_testing.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/ci_testing.yml b/.github/workflows/ci_testing.yml index 0cd0ae5..3db7ce1 100644 --- a/.github/workflows/ci_testing.yml +++ b/.github/workflows/ci_testing.yml @@ -57,6 +57,11 @@ jobs: codespell site/ - name: Grammar Check run: | + git remote add origin https://github.com/DOI-USGS/asc-public-docs.git + git remote fetch origin main + # List the files that changed + git diff --name-only origin/main + # Grammar check only those files git diff --name-only origin/main | grep -e .md -e .MD | sed 's/^/"/;s/$/"/' | xargs -t -L1 gramma check -p || true Link-Check: From e2111af062be6d492b0f898ac9fdcfddda383060 Mon Sep 17 00:00:00 2001 From: Kelvin Date: Tue, 5 Dec 2023 16:12:49 -0700 Subject: [PATCH 2/9] Typo lmao --- .github/workflows/ci_testing.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci_testing.yml b/.github/workflows/ci_testing.yml index 3db7ce1..100049b 100644 --- a/.github/workflows/ci_testing.yml +++ b/.github/workflows/ci_testing.yml @@ -58,7 +58,7 @@ jobs: - name: Grammar Check run: | git remote add origin https://github.com/DOI-USGS/asc-public-docs.git - git remote fetch origin main + git fetch origin main # List the files that changed git diff --name-only origin/main # Grammar check only those files From e13d59ff7216c454ec6691e666fef164f3fad48c Mon Sep 17 00:00:00 2001 From: Kelvin Date: Tue, 5 Dec 2023 16:14:59 -0700 Subject: [PATCH 3/9] Minor change to trigger grammar check --- docs/getting-started/using-isis-first-steps/adding-spice.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/getting-started/using-isis-first-steps/adding-spice.md b/docs/getting-started/using-isis-first-steps/adding-spice.md index f7b0e73..78e74d1 100644 --- a/docs/getting-started/using-isis-first-steps/adding-spice.md +++ b/docs/getting-started/using-isis-first-steps/adding-spice.md @@ -40,3 +40,4 @@ applications you will need to use to perform this procedure: - [**spiceinit**](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/spiceinit/spiceinit.html) : adds SPICE information to the input cube + From 3f0baadc8658ddb19de0ab9200bb6fa0e8362be3 Mon Sep 17 00:00:00 2001 From: Kelvin Date: Thu, 8 Feb 2024 21:57:10 -0700 Subject: [PATCH 4/9] Updated support docs --- .../software-management/software-support.md | 55 ++++++++++++++++--- 1 file changed, 46 insertions(+), 9 deletions(-) diff --git a/docs/how-to-guides/software-management/software-support.md b/docs/how-to-guides/software-management/software-support.md index f66c7cd..b08e5f3 100644 --- a/docs/how-to-guides/software-management/software-support.md +++ b/docs/how-to-guides/software-management/software-support.md @@ -1,34 +1,52 @@ # Software Support -This document provides information about the software support process, including scheduling, project management tools and practices, issue soliciation, issue selection, and prioritization. +!!! Note "How to Submit Issues" + Our code is managed [via GitHub](https://github.com/DOI-USGS) -## Step 1: Scheduling the Support Sprint + Any issues with our software portfolio should be tracked in our repos through [GitHub issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues). Links for some our bigger repos: + + * [ISIS](https://github.com/DOI-USGS/ISIS3/issues) + * [ALE](https://github.com/DOI-USGS/ale/issues) + * [USGSCSM](https://github.com/DOI-USGS/usgscsm/issues) + + This document provides information about the software support process. That is, how our development team goes about addressing these issues. Including scheduling, project management tools and practices, issue soliciation, issue selection, and prioritization. + +## Support Sprint Process + +Support sprints are dedicated efforts, time-boxed to 3 weeks quarterly. We schedule these as part of our internal scheduling procedures, and support sprints are scheduled 3 to 6 weeks ahead of time. This includes a prioritization meeting where we go through the issues accross our repositories and put them in prioritization order. These meetings are open to the public. + +??? Question "How do I get Notified of Support Sprints and prioritization meetings?" + We email anyone who has opted in to our software support newsletter which includes when the support sprint was scheduled, when the prioritization meetings are happening, and a link to the meeting. These are sent shortly after it's scheduled and again right before the meeting. + + Sign up at [here](https://public.govdelivery.com/accounts/USDOIGS/signup/39118). + +### Step 1: Scheduling the Support Sprint While there is some leeway in the exact timing of each support sprint, the sprints must be scheduled quarterly and should be scheduled roughly 3 months apart. Project scheduling should be coordinated by the project/technical lead and the software lead during routine software scheduling meetings. After setting up the sprint schedule, the technical lead should create a software support board and communicate the schedule to contributors. -## Step 2: Setting up the Project Board +### Step 2: Setting up the Project Board Immediately after scheduling the support sprint, the technical lead should create a project board to facilitate the tracking, prioritization, and assignment of issues. This has traditionally taken the form of a GitHub [projects board](https://github.com/orgs/DOI-USGS/teams/astrogeology-developers/projects) or a GitHub [discussion post](https://github.com/DOI-USGS/ISIS3/discussions), both of which provide automated tracking for issues that are hosted on GitHub. !!! Note "Due to recent changes in permissions and organizational boundaries, project boards can only be created as private (within-organization), which precludes external contributors from viewing or editing the board." -## Step 3: Notifying the Community -With a project board in place, there is now a mechanism to store incoming issues, and the technical lead can notify the community of the upcoming sprint. There is no "correct" way to notify community members, but the recommended method is via an MS Teams calendar event, which allows the host to send an email with an associated meeting invitation. +### Step 3: Notifying the Community +With a project board in place, there is now a mechanism to store incoming issues, and the technical lead can notify the community of the upcoming sprint. A new GovDelivery bulletin. Bulletin are emails that get broadcasted to subscribers. This email should include: 1. The time of the prioritization meeting +1. Link to the meeting, a new meeting should be created every time via MS Teams. 1. The purpose of the meeting 1. The start / end date of the sprint 1. A solicitation for issues that are significant to the community 1. Instructions on getting issues added to the board. - ??? Tip "Optional Boilerplate Email for MS Teams Calendar Event" This meeting will be used to prioritize the issues found at < link to project board > for the upcoming support sprint scheduled < date range of support >. The list of issues found on the project board is currently incomplete. If the list doesn't contain work that you would like to see scheduled during this sprint, then feel free to add items to the list. For contributors outside the ASC, please note that organizational policy does not currently allow read/write access to internal project boards. If you'd like work to be scheduled during this sprint, please ensure that an issue has been created and email me at < your email > to get the work scheduled. -## Step 4: Selecting Additional Issues +### Step 4: Selecting Additional Issues Despite community engagement, contributors do not generally produce enough issues to ensure that there is enough work to fill the sprint. In this case, the technical lead should select additional issues. While these issues are chosen at the discretion of the technical lead, the following generally make good candidates for support sprints: - Bug fixes @@ -40,7 +58,7 @@ Despite community engagement, contributors do not generally produce enough issue !!! Note "While there is no correct number of issues for each support sprint, support sprints typically include 35 - 50 issues." -## Step 5: Prioritizing Issues +### Step 5: Prioritizing Issues Prioritization meetings are typically a loosely guided discussion in which the technical lead acts as the facilitator. Prioritization meetings generally follow a format such as: 1. Ask attendees if there are any last-minute issues that should be added. @@ -49,4 +67,23 @@ Prioritization meetings are typically a loosely guided discussion in which the t 1. Ask for any closing remarks ??? Note "Issue deferral" - Deferring an issue generally means "this is a good, important issue, but it requires further discussion." This discussion should not interrupt the flow of prioritization, and discussing deferred issues is usually a good final topic. \ No newline at end of file + Deferring an issue generally means "this is a good, important issue, but it requires further discussion." This discussion should not interrupt the flow of prioritization, and discussing deferred issues is usually a good final topic. + + +## Continous Support + +An additional 2 weeks per quarter are dedicated for handling small issues. We refer to this as continious support, as it's suppport time between dedicated sprints. This amounts to roughly 6 hours a week to stay on top of GitHub notifications. + +Examples of what is excpected to be worked during these continuous suport hours: + +1. Review small PRs +1. Iterate on already open PRs +1. Comment on issues +1. Participate in discussion boards +1. Resolving small issues + +Examples of what is **not** expected to be worked during these continuous support hours: + +1. Resolving complex issues requiring new PRs +1. Reviewing large PRs +1. Non-support related project work From a38c844962dfee536b68fc69c8ffd2b3f1865541 Mon Sep 17 00:00:00 2001 From: Kelvin Date: Fri, 9 Feb 2024 08:54:14 -0700 Subject: [PATCH 5/9] Addressed comments --- .../software-management/software-support.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/how-to-guides/software-management/software-support.md b/docs/how-to-guides/software-management/software-support.md index b08e5f3..a149821 100644 --- a/docs/how-to-guides/software-management/software-support.md +++ b/docs/how-to-guides/software-management/software-support.md @@ -1,19 +1,20 @@ # Software Support +This document provides information about the software support process. That is, how our development team goes about addressing these issues. Including scheduling, project management tools and practices, issue soliciation, issue selection, and prioritization. + + !!! Note "How to Submit Issues" Our code is managed [via GitHub](https://github.com/DOI-USGS) - Any issues with our software portfolio should be tracked in our repos through [GitHub issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues). Links for some our bigger repos: + Any issues with our software portfolio should be tracked in our repos through [GitHub issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues). Links for some our more active repos: * [ISIS](https://github.com/DOI-USGS/ISIS3/issues) * [ALE](https://github.com/DOI-USGS/ale/issues) * [USGSCSM](https://github.com/DOI-USGS/usgscsm/issues) - This document provides information about the software support process. That is, how our development team goes about addressing these issues. Including scheduling, project management tools and practices, issue soliciation, issue selection, and prioritization. - ## Support Sprint Process -Support sprints are dedicated efforts, time-boxed to 3 weeks quarterly. We schedule these as part of our internal scheduling procedures, and support sprints are scheduled 3 to 6 weeks ahead of time. This includes a prioritization meeting where we go through the issues accross our repositories and put them in prioritization order. These meetings are open to the public. +Support sprints are dedicated efforts, time-boxed to 3 weeks quarterly. We schedule these as part of our internal scheduling procedures. Support sprints are scheduled 3 to 6 weeks ahead of time. A public prioritization meeting is scheduled prior to starting a support sprint. A notification of this meeting will be made (see below for how to subscribe) to the support mailing list 3 to 6 weeks ahead of time. ??? Question "How do I get Notified of Support Sprints and prioritization meetings?" We email anyone who has opted in to our software support newsletter which includes when the support sprint was scheduled, when the prioritization meetings are happening, and a link to the meeting. These are sent shortly after it's scheduled and again right before the meeting. @@ -31,7 +32,8 @@ Immediately after scheduling the support sprint, the technical lead should creat !!! Note "Due to recent changes in permissions and organizational boundaries, project boards can only be created as private (within-organization), which precludes external contributors from viewing or editing the board." ### Step 3: Notifying the Community -With a project board in place, there is now a mechanism to store incoming issues, and the technical lead can notify the community of the upcoming sprint. A new GovDelivery bulletin. Bulletin are emails that get broadcasted to subscribers. + +The community is notifed via an email sent to anyone [subscribed to the newsletter](https://public.govdelivery.com/accounts/USDOIGS/signup/39118). This email should include: @@ -45,6 +47,10 @@ This email should include: ??? Tip "Optional Boilerplate Email for MS Teams Calendar Event" This meeting will be used to prioritize the issues found at < link to project board > for the upcoming support sprint scheduled < date range of support >. The list of issues found on the project board is currently incomplete. If the list doesn't contain work that you would like to see scheduled during this sprint, then feel free to add items to the list. For contributors outside the ASC, please note that organizational policy does not currently allow read/write access to internal project boards. If you'd like work to be scheduled during this sprint, please ensure that an issue has been created and email me at < your email > to get the work scheduled. +??? Danger "For USGS devs: What mechanism do we use to send these emails out?" + + We use GovDelivery to create bulletins. These bulletins are emails which are broadcasted to our subscribers who have signed up with the link mentioned above. If you do not know how to create these bulletins ask the software lead for details of how to sign up for and sign into GovDelivery. + ### Step 4: Selecting Additional Issues Despite community engagement, contributors do not generally produce enough issues to ensure that there is enough work to fill the sprint. In this case, the technical lead should select additional issues. While these issues are chosen at the discretion of the technical lead, the following generally make good candidates for support sprints: @@ -67,14 +73,14 @@ Prioritization meetings are typically a loosely guided discussion in which the t 1. Ask for any closing remarks ??? Note "Issue deferral" - Deferring an issue generally means "this is a good, important issue, but it requires further discussion." This discussion should not interrupt the flow of prioritization, and discussing deferred issues is usually a good final topic. + Deferring an issue generally means "this is a good, important issue, but it requires further discussion." This discussion should not interrupt the flow of prioritization. ## Continous Support -An additional 2 weeks per quarter are dedicated for handling small issues. We refer to this as continious support, as it's suppport time between dedicated sprints. This amounts to roughly 6 hours a week to stay on top of GitHub notifications. +An additional 6 hours per week between sprints are dedicated for handling small issues. We refer to this as continious support, as it's suppport time between dedicated sprints. This is mostly to stay on top of GitHub notifications. -Examples of what is excpected to be worked during these continuous suport hours: +Examples of what a developer is excpected to be worked during these continuous suport hours: 1. Review small PRs 1. Iterate on already open PRs @@ -82,7 +88,7 @@ Examples of what is excpected to be worked during these continuous suport hours: 1. Participate in discussion boards 1. Resolving small issues -Examples of what is **not** expected to be worked during these continuous support hours: +Examples of what a developer is **not** expected to be worked during these continuous support hours: 1. Resolving complex issues requiring new PRs 1. Reviewing large PRs From 7c04dd1acb434433f13267a68bc446920fd640a1 Mon Sep 17 00:00:00 2001 From: Kelvin Date: Fri, 9 Feb 2024 08:57:20 -0700 Subject: [PATCH 6/9] Fixed typo --- docs/how-to-guides/software-management/software-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/software-management/software-support.md b/docs/how-to-guides/software-management/software-support.md index a149821..d240bed 100644 --- a/docs/how-to-guides/software-management/software-support.md +++ b/docs/how-to-guides/software-management/software-support.md @@ -19,7 +19,7 @@ Support sprints are dedicated efforts, time-boxed to 3 weeks quarterly. We sched ??? Question "How do I get Notified of Support Sprints and prioritization meetings?" We email anyone who has opted in to our software support newsletter which includes when the support sprint was scheduled, when the prioritization meetings are happening, and a link to the meeting. These are sent shortly after it's scheduled and again right before the meeting. - Sign up at [here](https://public.govdelivery.com/accounts/USDOIGS/signup/39118). + Sign up [here](https://public.govdelivery.com/accounts/USDOIGS/signup/39118). ### Step 1: Scheduling the Support Sprint While there is some leeway in the exact timing of each support sprint, the sprints must be scheduled quarterly and should be scheduled roughly 3 months apart. Project scheduling should be coordinated by the project/technical lead and the software lead during routine software scheduling meetings. From 315d45e1080e2c279d6eea8ff11ad52f9cb162a8 Mon Sep 17 00:00:00 2001 From: Kelvin Date: Fri, 9 Feb 2024 09:57:55 -0700 Subject: [PATCH 7/9] Codespell fixes --- .../how-to-guides/software-management/software-support.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/how-to-guides/software-management/software-support.md b/docs/how-to-guides/software-management/software-support.md index d240bed..08b37f7 100644 --- a/docs/how-to-guides/software-management/software-support.md +++ b/docs/how-to-guides/software-management/software-support.md @@ -33,7 +33,7 @@ Immediately after scheduling the support sprint, the technical lead should creat ### Step 3: Notifying the Community -The community is notifed via an email sent to anyone [subscribed to the newsletter](https://public.govdelivery.com/accounts/USDOIGS/signup/39118). +The community is notified via an email sent to anyone [subscribed to the newsletter](https://public.govdelivery.com/accounts/USDOIGS/signup/39118). This email should include: @@ -76,11 +76,11 @@ Prioritization meetings are typically a loosely guided discussion in which the t Deferring an issue generally means "this is a good, important issue, but it requires further discussion." This discussion should not interrupt the flow of prioritization. -## Continous Support +## Continuous Support -An additional 6 hours per week between sprints are dedicated for handling small issues. We refer to this as continious support, as it's suppport time between dedicated sprints. This is mostly to stay on top of GitHub notifications. +An additional 6 hours per week between sprints are dedicated for handling small issues. We refer to this as continuous support, as it's support time between dedicated sprints. This is mostly to stay on top of GitHub notifications. -Examples of what a developer is excpected to be worked during these continuous suport hours: +Examples of what a developer is expected to be worked during these continuous support hours: 1. Review small PRs 1. Iterate on already open PRs From 1bb86a3097db4ece115a2133f1c040df035bb7e6 Mon Sep 17 00:00:00 2001 From: Kelvin Date: Fri, 9 Feb 2024 16:17:25 -0700 Subject: [PATCH 8/9] Addressed more comments --- .../software-management/software-support.md | 21 ++++++------------- 1 file changed, 6 insertions(+), 15 deletions(-) diff --git a/docs/how-to-guides/software-management/software-support.md b/docs/how-to-guides/software-management/software-support.md index 08b37f7..deba3b3 100644 --- a/docs/how-to-guides/software-management/software-support.md +++ b/docs/how-to-guides/software-management/software-support.md @@ -24,12 +24,11 @@ Support sprints are dedicated efforts, time-boxed to 3 weeks quarterly. We sched ### Step 1: Scheduling the Support Sprint While there is some leeway in the exact timing of each support sprint, the sprints must be scheduled quarterly and should be scheduled roughly 3 months apart. Project scheduling should be coordinated by the project/technical lead and the software lead during routine software scheduling meetings. -After setting up the sprint schedule, the technical lead should create a software support board and communicate the schedule to contributors. +After setting up the sprint schedule, we create a software support board and communicate the schedule to contributors. The prioritization meeting should be scheduled some day the week before the support sprint. ### Step 2: Setting up the Project Board Immediately after scheduling the support sprint, the technical lead should create a project board to facilitate the tracking, prioritization, and assignment of issues. This has traditionally taken the form of a GitHub [projects board](https://github.com/orgs/DOI-USGS/teams/astrogeology-developers/projects) or a GitHub [discussion post](https://github.com/DOI-USGS/ISIS3/discussions), both of which provide automated tracking for issues that are hosted on GitHub. -!!! Note "Due to recent changes in permissions and organizational boundaries, project boards can only be created as private (within-organization), which precludes external contributors from viewing or editing the board." ### Step 3: Notifying the Community @@ -73,23 +72,15 @@ Prioritization meetings are typically a loosely guided discussion in which the t 1. Ask for any closing remarks ??? Note "Issue deferral" - Deferring an issue generally means "this is a good, important issue, but it requires further discussion." This discussion should not interrupt the flow of prioritization. + Deferring an issue generally means "this is a good, important issue, but it requires further discussion." This discussion should not interrupt the flow of prioritization. ## Continuous Support -An additional 6 hours per week between sprints are dedicated for handling small issues. We refer to this as continuous support, as it's support time between dedicated sprints. This is mostly to stay on top of GitHub notifications. +Internal developers have time to perform basic support tasks throughout the week. We refer to this as continuous support, as it's support time between dedicated sprints. This is to stay on top of GitHub notifications. -Examples of what a developer is expected to be worked during these continuous support hours: +As a user, you should expect feedback on an issue within a week of posting. If urgent, you can ping `@DOI-USGS/astrogeology-developers`. If the GitHub issue is open with no activity for a long enough time it will become stale and eventually auto-closed. Often, issues are not ignored, but are saved for a support sprint. -1. Review small PRs -1. Iterate on already open PRs -1. Comment on issues -1. Participate in discussion boards -1. Resolving small issues +??? Danger "Continuous Support and internal Developers" -Examples of what a developer is **not** expected to be worked during these continuous support hours: - -1. Resolving complex issues requiring new PRs -1. Reviewing large PRs -1. Non-support related project work + See the [internal software support docs](https://code.chs.usgs.gov/asc/ASC_Software_Docs/-/blob/main/Software%20Management/Continuous%20Support.md) for more information on continuous support. \ No newline at end of file From 0c3161507c93b549a26122e2e3db3ac520273045 Mon Sep 17 00:00:00 2001 From: Kelvin Date: Mon, 12 Feb 2024 20:26:20 -0700 Subject: [PATCH 9/9] Removed CS stuff --- .../software-management/software-support.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/docs/how-to-guides/software-management/software-support.md b/docs/how-to-guides/software-management/software-support.md index deba3b3..6f523cb 100644 --- a/docs/how-to-guides/software-management/software-support.md +++ b/docs/how-to-guides/software-management/software-support.md @@ -46,11 +46,6 @@ This email should include: ??? Tip "Optional Boilerplate Email for MS Teams Calendar Event" This meeting will be used to prioritize the issues found at < link to project board > for the upcoming support sprint scheduled < date range of support >. The list of issues found on the project board is currently incomplete. If the list doesn't contain work that you would like to see scheduled during this sprint, then feel free to add items to the list. For contributors outside the ASC, please note that organizational policy does not currently allow read/write access to internal project boards. If you'd like work to be scheduled during this sprint, please ensure that an issue has been created and email me at < your email > to get the work scheduled. -??? Danger "For USGS devs: What mechanism do we use to send these emails out?" - - We use GovDelivery to create bulletins. These bulletins are emails which are broadcasted to our subscribers who have signed up with the link mentioned above. If you do not know how to create these bulletins ask the software lead for details of how to sign up for and sign into GovDelivery. - - ### Step 4: Selecting Additional Issues Despite community engagement, contributors do not generally produce enough issues to ensure that there is enough work to fill the sprint. In this case, the technical lead should select additional issues. While these issues are chosen at the discretion of the technical lead, the following generally make good candidates for support sprints: @@ -75,12 +70,3 @@ Prioritization meetings are typically a loosely guided discussion in which the t Deferring an issue generally means "this is a good, important issue, but it requires further discussion." This discussion should not interrupt the flow of prioritization. -## Continuous Support - -Internal developers have time to perform basic support tasks throughout the week. We refer to this as continuous support, as it's support time between dedicated sprints. This is to stay on top of GitHub notifications. - -As a user, you should expect feedback on an issue within a week of posting. If urgent, you can ping `@DOI-USGS/astrogeology-developers`. If the GitHub issue is open with no activity for a long enough time it will become stale and eventually auto-closed. Often, issues are not ignored, but are saved for a support sprint. - -??? Danger "Continuous Support and internal Developers" - - See the [internal software support docs](https://code.chs.usgs.gov/asc/ASC_Software_Docs/-/blob/main/Software%20Management/Continuous%20Support.md) for more information on continuous support. \ No newline at end of file