= Managing SDPi Development Using GitHub Projects

:toc: right

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


image::./images/SDPi-FHIR-Project-Tooling-Overview.png[ToI,500,,,align="center"]


== 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  [[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:

. *New Issue Created*
.. Add initial issue *Title*
*** Note:  May update later based on issue type / label template & guidelines
.. Add *issue description* in the "Write - Leave a comment" section
.. Select *Project*(s)
*** Issue will show up on the Project Kanban Board's "To do" column
.. 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.)
.. Add *Milestone*(s)
***  Either create or link to one or more of the Project's milestones
.. *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 ...

["arabic", start=2]
. *Branch* the Repository
*** This should trigger moving the issue from the "To do" to the "In progress" column
.  *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
.  *Reviewer Requests Changes*
*** This will move the issue to the "Review in progress" column
.  *Reviewer Approvals*
*** Once the required number of reviewers have approved the branch updates,
.  *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:

. Change Issue / Projects / status from "To do" to "In progress";
. If necessary, manually move the related To Do item(s) to the "In progress" column on the project's kanban board
. Create a branch for the issue (see the "Development" item on the items on the right)
. FOR each Issue sub-task
.. "Convert to issue" - highlight the task and select the radial button on the right
.. Configure the new issue (which has the name of the task's text)
.. Create a branch for this subtask issue
. Work on branch(es)
.. Change issue status to "In progress"
.. link:Updating-the-Changelog[Update the CHANGELOG.md]
. Open one Pull Request (PR) per branch (main issue or subtask) once work is completed
.. Change issue status to "Review in progress"
.. Preform review process for each branch, approving each as completed
. Merge each PR once the review and approval is completed
. 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!

{empty} +

== Tracking Progress Against Milestones

#TODO:  Craft how to use github milestones for the tracking of multi-issue coordination around major capabilities / updates.  See https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/creating-and-editing-milestones-for-issues-and-pull-requests[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
[source,mermaid]
....
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))
....

=== 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 link:https://github.com/IHE/DEV.SDPi[SDPi home page], a click on link:https://github.com/IHE/DEV.SDPi/releases/new[_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 link:https://github.com/HL7/DEV.SDPi[HL7 SDPi Github page] one day later, starting at __Create Release Page__.