Content
View differences
Updated by Philipp Tessenow over 5 years ago
# User Problem
## User
_What persona, persona segment, or customer type experiences the problem most acutely?_
* Software developer
## Problem
_What problem or job does the user have?_
* Roadmap planning is in OpenProject, but development happens in GitHub.
* Developers need to manually synchronize state between OpenProject and Github
* When pairing/continuing on existing work packages, it is not immediately clear if there is existing work and where to find it on GitHub
## Pain
_What is the primary workaround that users perform that we could remove or replace? Why is it painful?_
* Developer needs to manually do a lot of setup tasks before starting to code:
* Create PR with reference to work package ID in description
* Create branch name
* Provide a PR/commit description, making sure all points from the original work package are covered
* Commit messages and branch names are inconsistent. There is no guidance/defaults.
* The existing GitHub integration comments on work packages, but gives no good overview (as comments get lost)
* The state of a work package could better sync with the PR progress (`Draft PR created` > `Ready for review` > review >` `closed || merged`)
* When teaming up with existing work (taking over a PR or pairing on an existing branch), one has to manually search GitHub for existing PRs or ask the original developer for a branch name.
* As an OpenProject administrator, it is hard to set up our current GitHub integration (it requires a "GitHub" user on OpenProject and manually crafted webhooks on GitHub)
## Solution
_How do we solve the user’s problem. What is our “pain killer”? What must we achieve in the first version of the solution in order to achieve value for the user?_
We aim to automate the workflow of synchronizing state between GitHub and OpenProject as much as possible. At the same time we strive to keep information intended for application-specific use cases in their specific apps. For example, we would keep code-review comment in GitHub PRs (not copying them over to OpenProject), and only reference the existence of a PR in OpenProject. At the same time we do not copy OpenProject work package comments over to GitHub.
### Use Case: Start development of a work package
* As a developer, I can open a work packages details page to find a new "Development" Tab in the sidebar next to "Activity", "Relations", and "Watchers".
* It is initially empty (as no GitHub PR was linked yet), except for a "Create PR" button
* Pressing the "Create PR" button, automatically creates a new Draft Pull Request on the GitHub repository linked to the project. The PR contains a new commit with a pre-filled commit message on a new feature branch with an automatically generated name. An example branch name could be `idea/3867-openproject-github-pull-request-integration` with an example commit message being:
* the Pull Request contains the same subject and body as the commit
```text
[#3867] Idea: OpenProject - GitHub Pull Request Integration
[Ticket](https://community.openproject.com/projects/openproject/work_packages/3867)
We want to integrate our pull request workflow with our OpenProject workflow more tightly.
The following features would be nice to have:
* ...
* ...
... (most of the example work package description is intentionally skipped to keep this example small)
```
* The "Development" sidebar automatically lists the newly created PR with a link to its GitHub page.
* optional: An additional button is show which copies a "git checkout" command (`git fetch && git checkout idea/3867-openproject-github-pull-request-integration`) to the users clipboard.
### Use Case: Progress on a work package
* ...
### Use Case: Continuing existing work on a work package
* ...
### Use Case: Finishing a work package
* ...
### Use Case: Set-Up a new project with GitHub integration
* ...
### Use Case: Time logging
* ...
### Use Case: Comments that should be synced from GitHub to OpenProject
* ...
Niels initial thoughts:
* Developer can push a button "Create PR" in the work package.
* OpenProject calls GitHub API
* Create branch (following the naming scheme)
* Create commit with pre-filled description and title
* Create PR
* Global admininistration form for oAuth authentication flow to request permission to do stuff in Github
* Project settings: Add reference to GitHub repository
## Out of Scope for the MVC
_What should NOT be in the minimal viable change, and can be considered for future iterations? Why? Please order them by importance._
* User-based authentication.
* Bi-directional sync of issues between OpenProject and Github
* Configurations for naming scheme
## Differentiation
_What do you believe will differentiate us from the current experience or competitive experiences?_
* ...
## Next iteration
_What is the next solution that would allow us to release meaningful customer value quickly?_
* Use PR comments for additional actions
* Log time
# Launch and Growth
## Measures
_How will you know you solved the problem? Please list measurable, quantitative indicators (preferred) or qualitative ways you plan on assessing the solution?_
* ...
## Messaging
_If you were to write a press release, how would you describe the value to customers?_
<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><tbody><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head">Headline</th><td class="op-uc-table--cell"></td></tr><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head">First Paragraph</th><td class="op-uc-table--cell"></td></tr><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head">Customer Quote</th><td class="op-uc-table--cell"></td></tr></tbody></table></figure>
## Go to market
_How are you planning on getting this into users' hands?_
## User
_What persona, persona segment, or customer type experiences the problem most acutely?_
* Software developer
## Problem
_What problem or job does the user have?_
* Roadmap planning is in OpenProject, but development happens in GitHub.
* Developers need to manually synchronize state between OpenProject and Github
* When pairing/continuing on existing work packages, it is not immediately clear if there is existing work and where to find it on GitHub
## Pain
_What is the primary workaround that users perform that we could remove or replace? Why is it painful?_
* Developer needs to manually do a lot of setup tasks before starting to code:
* Create PR with reference to work package ID in description
* Create branch name
* Provide a PR/commit description, making sure all points from the original work package are covered
* Commit messages and branch names are inconsistent. There is no guidance/defaults.
* The existing GitHub integration comments on work packages, but gives no good overview (as comments get lost)
* The state of a work package could better sync with the PR progress (`Draft PR created` > `Ready for review` >
* When teaming up with existing work (taking over a PR or pairing on an existing branch), one has to manually search GitHub for existing PRs or ask the original developer for a branch name.
* As an OpenProject administrator, it is hard to set up our current GitHub integration (it requires a "GitHub" user on OpenProject and manually crafted webhooks on GitHub)
## Solution
_How do we solve the user’s problem. What is our “pain killer”? What must we achieve in the first version of the solution in order to achieve value for the user?_
We aim to automate the workflow of synchronizing state between GitHub and OpenProject as much as possible. At the same time we strive to keep information intended for application-specific use cases in their specific apps. For example, we would keep code-review comment in GitHub PRs (not copying them over to OpenProject), and only reference the existence of a PR in OpenProject. At the same time we do not copy OpenProject work package comments over to GitHub.
### Use Case: Start development of a work package
* As a developer, I can open a work packages details page to find a new "Development" Tab in the sidebar next to "Activity", "Relations", and "Watchers".
* It is initially empty (as no GitHub PR was linked yet), except for a "Create PR" button
* Pressing the "Create PR" button, automatically creates a new Draft Pull Request on the GitHub repository linked to the project. The PR contains a new commit with a pre-filled commit message on a new feature branch with an automatically generated name. An example branch name could be `idea/3867-openproject-github-pull-request-integration` with an example commit message being:
* the Pull Request contains the same subject and body as the commit
```text
[#3867] Idea: OpenProject - GitHub Pull Request Integration
[Ticket](https://community.openproject.com/projects/openproject/work_packages/3867)
We want to integrate our pull request workflow with our OpenProject workflow more tightly.
The following features would be nice to have:
* ...
* ...
... (most of the example work package description is intentionally skipped to keep this example small)
```
* The "Development" sidebar automatically lists the newly created PR with a link to its GitHub page.
* optional: An additional button is show which copies a "git checkout" command (`git fetch && git checkout idea/3867-openproject-github-pull-request-integration`) to the users clipboard.
### Use Case: Progress on a work package
* ...
### Use Case: Continuing existing work on a work package
* ...
### Use Case: Finishing a work package
* ...
### Use Case: Set-Up a new project with GitHub integration
* ...
### Use Case: Time logging
* ...
### Use Case: Comments that should be synced from GitHub to OpenProject
* ...
Niels initial thoughts:
* Developer can push a button "Create PR" in the work package.
* OpenProject calls GitHub API
* Create branch (following the naming scheme)
* Create commit with pre-filled description and title
* Create PR
* Global admininistration form for oAuth authentication flow to request permission to do stuff in Github
* Project settings: Add reference to GitHub repository
## Out of Scope for the MVC
_What should NOT be in the minimal viable change, and can be considered for future iterations? Why? Please order them by importance._
* User-based authentication.
* Bi-directional sync of issues between OpenProject and Github
* Configurations for naming scheme
## Differentiation
_What do you believe will differentiate us from the current experience or competitive experiences?_
* ...
## Next iteration
_What is the next solution that would allow us to release meaningful customer value quickly?_
* Use PR comments for additional actions
* Log time
# Launch and Growth
## Measures
_How will you know you solved the problem? Please list measurable, quantitative indicators (preferred) or qualitative ways you plan on assessing the solution?_
* ...
## Messaging
_If you were to write a press release, how would you describe the value to customers?_
<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><tbody><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head">Headline</th><td class="op-uc-table--cell"></td></tr><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head">First Paragraph</th><td class="op-uc-table--cell"></td></tr><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head">Customer Quote</th><td class="op-uc-table--cell"></td></tr></tbody></table></figure>
## Go to market
_How are you planning on getting this into users' hands?_