# MigEng workflow proposal
###### tags: `Documentation`

I have thought pretty extensively about this in the past for MTC and developed
a process that I hoped met two conflicting needs:

* The developers want to work in Github the majority of the time.
* Jira is a necessity for downstream activities (errata) and our other stakeholder teams
(QE, Docs) also strongly prefer to work here.
* Zenhub was also piloted but abandonded. Jira is a necessity, and a adding a
third tool to the equation is a net negative.

My solution expected PRD type definitions (Product Requirements Document)
to be written and committed to Jira as the golden source.

### Stealing a "what is part of a PRD"?
* Objective/Goal: Explain why are you building this and what do you hope to accomplish.

* Features: For each feature, you should include a description, goal and use
case at a minimum. Additional details may be helpful or necessary depending on
the complexity of the feature, such as out-of-scope items.

* UX Flow & Design Notes: Most organizations complete the UX design of features
after the PRD has been reviewed and accepted. However, there may be some general
guidance required at this stage to ensure the release objectives are met. This
is not the place for pixel-perfect mockups or wireframes that map out every
possible scenario; instead, it can be used to describe the overall user workflow.

* System & Environment Requirements: Which end-user environments will be
supported (such as browsers, operating systems, memory, and processing power, etc.).

* Assumptions, Constraints & Dependencies: List out what is expected of users,
any limits for the implementation to be aware of and any outside elements
required for the final solution to be functional.

**So a document that describes what problem are we solving, use-cases are we covering,
and why**

### Functional Spec
How we're going to build the solution. Generally I wanted this to be in github
because it's the engineer's domain:

--

## Proposal:
* All bugs in Jira as a golden source. This allows QE to work their lifecycle
from jira as their comfortable and we can attach them to errata. It eliminates
a third system: Bugzilla.

* PRD content belongs in Jira. The Epics that are getting worked and the User
stories that are being pursued. Further, our team makes extensive use of "Spikes",
typically investigative tasks that produce an Enhancement as a deliverable. This
includes problem background, different proposed solutions, and what has been
accepeted and/or rejected.

> OPINION: I strongly prefer Jira for the above type content. Github currently
does not have the primitives that I use constantly in order to query a backlog
of 1000+ issues, married with a concept of sprints, roadmaps, and releases.

#### Workflow
User stories and spikes are organized on sprintboards. It's the owning
engineer's responsibility to create Github issues with [MIG-XXX] in the title
that break down the story into implementable tasks to be worked. Wadsworth bot [1]
will auto link these issues as subtasks to the user story. As PRs are posted
with "closes #<issue-num>" in the title, upon review and merge of the PR, the
issue automatically gets closed by github's native automation. Wadsworth gets
an event and pushes the Jira subtask to Done. When all subtasks are Done, the
story moves to QE state for QE to being their test process. The engineer still
needs to review and approve test plans which live in polarian, indicated by
a "tc_approved" label on the Jira.

The end result is that the majority of the time, the engineer lives in github
creating issues for implementation tasks and working those tasks by submitting
PRs that will naturally propagate a completion event to Jira through automation.

PM is able to author PRD style requirements in Jira. QE works off of the User
Stories in Jira, and Docs works off of Jira stores as well, documenting our
features as laid out there.

[1]https://github.com/konveyor/wadsworth