Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Software support docs update #35

Merged
merged 10 commits into from
Feb 13, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 32 additions & 12 deletions docs/how-to-guides/software-management/software-support.md
Original file line number Diff line number Diff line change
@@ -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.

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.

## Step 1: Scheduling the Support Sprint

!!! 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 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)

## Support Sprint Process

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.

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.

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
### 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

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:

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
Expand All @@ -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.
Expand All @@ -49,4 +67,6 @@ 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.


Loading