Managing SDPi Development Using GitHub Projects

Managing SDPi Development Using GitHub Projects

TODO: Add general workflow and approach using GitHub Projects, Issues, Kanban board, workflow, milestones, automation, etc. ALSO reference the general article on the home page about doing Gemini work & project planning

GitHub Projects - Overview & Co-working Space

TODO: Basic rationale for using github projects / issues / automation / kanban board / workflow / milestones / etc. + "classic" vs. "new" projects, projects for AsciiDoc based guidance documents - Gemini SES+MDI projects NOT managed in github???

See the related article "Program Coordination Co-Working Spaces" <add a link to the article here> Include graphic with flow from confluence to smartsheet (or Excel) to github stuff below

Creating New Projects

TODO: include links to relevant articles; projects that are already created vs. projects to be updated

Linking Projects to Wiki Updates

#TODO: Provide guidance and perhaps a CHECKLIST? for project Issues managed in the repo to updates to be made to the wiki documentation

Workflow Using Issues & Automation

TODO: Chart how to use automation and github "issues" to manage tasks and updates to the SDPi specifications and other work products (e.g., documents)

Issue Creation

For each Issue

Note: Issues are plan tasks that have no sub tasks higher order tasks become milestones

QUESTION: Issues outside of milestones? Issues that are also a milestone?

Issue Automation / Project Kanban Board

Project & issue "automation" is accomplished as follows:

1. New Issue Created

   1. Add initial issue Title

      • Note: May update later based on issue type / label template & guidelines

   2. Add issue description in the "Write - Leave a comment" section

   3. Select Project(s)

      • Issue will show up on the Project Kanban Board’s "To do" column

   4. Add appropriate Label(s), including:

      • Specification - New content to be added to the SDPi specification

      • Topic of Interest - Resolution of an issue (ToI) that is ready to be integrated into the specification (e.g., OID extensions)

      • Spec Fix - Problem in the current version of the SDPi specification that needs to be fixed (e.g., broken link, incomplete sentences, etc.)

      • Review Comment - a comment that was received from the domain internal or public comment review phases

      • Wiki Content - New content that needs to be documented in the repo’s wiki; note: though the wiki can be branched, that branching is not supported in the

      • Wiki Fix - Issues with currently published wiki content (e.g., broken links, typos, etc.)

   5. Add Milestone(s)

      • Either create or link to one or more of the Project’s milestones

   6. Assign people to Issue

      • Note: Individuals have to first be added to the IHE github community; let Todd Cooper or John Rhoads know if this needs to be done

At this point, the Issue should be shown on the project’s kanban board’s "To do" column When work is ready to begin …​

2. Branch the Repository

   • This should trigger moving the issue from the "To do" to the "In progress" column

3. Pull Request to Initiate Review

   • This will let others know that changes have been pushed to the branch and are ready for review, BUT the issue will stay in the "In progress" column

4. Reviewer Requests Changes

   • This will move the issue to the "Review in progress" column

5. Reviewer Approvals

   • Once the required number of reviewers have approved the branch updates,

6. Merge Updates / Close Issue

   • When this is complete, the Issue will move to the "Done" Column

Issue Workflow: From "To do" to Closed & Merged

Once an issue is created (see Issue Creation above), and developers are ready to begin actively working on the tasks, the following issue workflow should be followed:

1. Change Issue / Projects / status from "To do" to "In progress";

2. If necessary, manually move the related To Do item(s) to the "In progress" column on the project’s kanban board

3. Create a branch for the issue (see the "Development" item on the items on the right)

4. FOR each Issue sub-task

   1. "Convert to issue" - highlight the task and select the radial button on the right

   2. Configure the new issue (which has the name of the task’s text)

   3. Create a branch for this subtask issue

5. Work on branch(es)

   1. Change issue status to "In progress"

   2. Update the CHANGELOG.md

6. Open one Pull Request (PR) per branch (main issue or subtask) once work is completed

   1. Change issue status to "Review in progress"

   2. Preform review process for each branch, approving each as completed

7. Merge each PR once the review and approval is completed

8. Close the issue - first for each task then for the main issue itself

Warning

This process may be "tweaked" with more team experience, but it is a good starting point!

Tracking Progress Against Milestones

TODO: Craft how to use github milestones for the tracking of multi-issue coordination around major capabilities / updates. See Using Labels and Milestones to Track Work…​

Note: SmartSheet "Finish" milestones are at the task level where there are no further subtasks; some discretion should be applied!

<note %completion is in github not SmartSheet!>

"Bug" Fix Management via Labels

In order to capture discrepancies or "bugs" with the SDPi specification and related artifacts / documentation, a special set of issues have been defined and can be associated with any Github Issue that is created. Currently only two labels have been defined: "Spec Fix" and "Wiki Fix"; however, more may be added in the future, if finer level of distinction are needed.

Taking this approach enables easy searching of existing "bugs" associated with Issues: "https://github.com/IHE/DEV.SDPi/labels/<label name>"

Of course, search filters can be created for repeated fix management tracking efforts.

Caution

Label naming conventions may change in the future. For example, to remove spaces (use underlines instead) and only lower case characters. This would make simple ad hoc searches using the example URL above much simpler to remember. Just sayin' …​

Running an SDPi release

This section describes the process to create an SDPi release on Github.

Release process

flowchart TD
    start((Start)) --> createtag[Create Tag]
    createtag[Create Tag] --> buildtag[Get Master Build ZIP for Tag]
    buildtag[Get Master Build ZIP for Tag] --> createreleasepage[Create Release Page]
    createreleasepage[Create Release Page] --> Configure
    subgraph Configure
        direction TB
        addtag[Apply Tag]
        addtitle[Add title]
        addchangeloglink[Add Changelog Link]
        uploadzip[Upload ZIP]
    end
    Configure --> stop((Stop))

Loading

Create Release Branch

First, we need a release branch to conserve the state for which we want to generate a release:

$ git checkout master
$ git pull
$ git branch -b release-X.Y.Z
$ git push origin release-X.Y.Z

Create Tag

Second, a version release tag needs to be created based on the release branch.

$ git checkout release-X.Y.Z
$ git tag X.Y.Z
$ git push origin X.Y.Z

Get Release Branch Build ZIP for Tag

Download the artifact from the release branch build. This ensures coherency between the tag and the build artifact that will appear on the release page.

Create Release Page

On the SDPi home page, a click on Create new release opens the dialog to configure and add a new release.

Configure

Apply Tag

On the top, choose the tag that was created corresponding to the released document.

Add title

Add a release title. For a Trial Implementation release, the title is Release of X.Y.Z for TI.

Add Changelog Link

Add a link to the changelog that belongs to the chosen tag:

[📋Please click here for a detailed changelog](https://github.com/HL7/DEV.SDPi/blob/X.Y.Z/CHANGELOG.md)

This spares the release author to copy-paste the information from the changelog.

Upload ZIP

Down below on the release page, the downloaded ZIP file has to be uploaded to provide an offline copy of the release.

Pre-release

For any release that is not going into production, select Set as a pre-release.

Once done, hit the Publish release button.

Important

The release page has to be created on the HL7 SDPi Github page one day later, starting at Create Release Page.