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?_
* Project management, team collaboration and roadmap planning is done in OpenProject, but software development happens on GitHub.
* Developers need to manually synchronize state of their work 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` > `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 1: 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 2: Sync progress of a Pull Request with work package
* Given there is development progress on a PR, status transitions can be configured on a per-project basis that are applied to the linked work package
* The following GitHub actions can be configured:
* Draft PR is marked as "ready for review"
* A PR was merged
* A PR was closed without merging
* The OpenProject "development" sidebar shows the current status of any linked PR (draft, open, closed, merged) along with the GitHub user who created the PR
## Use Case 3: Link a manually created Pull Request to a work package
* It is possible to link PRs to a work package without using the "Create PR" button mentioned before by mentioning the ticket-code in brackets in a PR subject, a PR body, or a commit message. The work package code for a work package with the ID 3867 is `[#3867]`.
* Using this method, it is possible to link multiple PRs to a single work package
> It is not possible to link multiple PRs to a single work package?
## Use Case 4: Set-Up a new project with GitHub integration
* We add a new instance-wide configuration setting to authenticate the OpenProject instance against a GitHub organization or user, using the ["GitHub App OAuth flow"](https://docs.github.com/en/developers/apps/authorizing-oauth-apps).
* We add a new project configuration page which allows to select a GitHub repository from a list of repositories OpenProject has access to using the GitHub App mentioned above.
* This page also allows to configure state transitions on PR updates, see: "Use Case: Progress on a Pull Request"
> Workflows are the same in OpenProject throughout all projects. So I am wondring if we need to have different mappings on a project level.
## Use Case 5: Create links to OpenProject work packages in PR descriptions
* When a PR is created, edited or a new comment was added on GitHub, OpenProject scans the text for work package codes (e.g. `[#3867]`) and replaces these with links to the respective work package.
* This assumes a project is linked to the repository and the project has a work package with the mentioned ID.
# 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._
## Use Case: Additional work on a Pull Request
_This use case is considered an addition to the MVP, but was requested by AMG in a call on 2020-02-01._
* There is other types of work possible on Pull Requests than just status changes:
* A review was done (being a comment/approval/rejection) by a specific GitHub user
* A "check" (like CI/CD) was run with a state (success/error/pending) and a message (e.g. link to a test-platform)
* Ideally, we show that information (with a link pointing to the respective GitHub details page) in the development sidebar beneath the linked pull request.
## Use Case: Time logging
_This use case is considered an addition to the MVP, but was requested by an internal open project call on 2020-02-01._
* Developers are able to log time on a linked work package by writing an "openproject-command" , e.g.: `@openproject book_time 1h`
* Note: the actual syntax is subject to change (especially `@openproject` as this notation is already picked-up by GitHub to link against a GitHub-user named "openproject")
* times may be provided as of [the following regex `/\d+(\.\d+)?[mhd]/`](https://rubular.com/r/Pe1Q8iauJ55G2n) booking time for the given amount of minutes/hours/days (given an 8-hour work day). An openproject command must be the only text on its line.
* Note: This use case was briefly mentioned and filled-in by tessi, we need to check this against the reality of time booking in open project :)
## Use Case: Comments that should be synced from GitHub to OpenProject
_This use case is considered an addition to the MVP, but was requested by an internal open project call and an AMG call on 2020-02-01._
* Normally no GitHub communication is linked to OpenProject
* Developers are able to add a reference to the current GitHub communication thread to the linked work package by using an open project command \`@openproject mention\`
* Note: the actual command is subject to change (see "Use Case: Time logging")
* Once the command is noticed, a new comment appears on OpenProject which cites the GitHub message and links to it.
* GitHub messages that can contain this command are:
* PR descriptions
* PR comments
* commit comments
* commit messages
* review comments
## Use Case: Link OpenProject users with GitHub users
* When showing development updates in OpenProject, we usually show GitHub usernames. Ideally we could find a matching OpenProject-user to every mentioned GitHub-user and show the avatar/username of the OpenProject user.
## Use Case: Sync milestones between OpenProject and GitHub
* Both, GitHub and OpenProject, have a milestone feature. We may be able to sync milestones between them.
## Use Case: Configure scheme for default branch names and commit messages
* Not all work packages are targeting feature branches, thus their naming scheme for branches or commit messages may differ. Also, different project may have different naming schemes. It should be possible to adapt the default branch names / messages on a per-project bases.
## Use Case: See GitHub API Status
* Our API may be perceived as slow or buggy when GitHub has problems. We could fetch [the GitHub API status](https://www.githubstatus.com/api/#status) and display a warning message if webhooks or other APIs we use are impacted.
# Differentiation
_What do you believe will differentiate us from the current experience or competitive experiences?_
Comparison to the existing GitHub plugin
* Set-up of the current plugin is hard to do right (required a "GitHub" user and correctly places webhooks). This solution would automate the GitHub-facing configuration using the GitHub API.
* The current plugin only comments on PR changes (sometimes too often, e.g. when a PR is edited), these comments tend to get lost in long comment threads. Our solution provides a better overview by using a separate "development" sidebar tab
* The proposed solution is able to show more information of a PR than just it's state, e.g. CI/CD state or reviews
* The solution is extensible using more "openproject commands" on github
Comparison to the competition
* Showing the state of a PR and linking them to issues/tickets is a given for most mature project management software (Jira)
* Our feature of starting the work flow with default branches/messages is new ([there are existing OpenSource solutions working as browser plugins](https://github.com/bitcrowd/tickety-tick/))
# Next iteration
_What is the next solution that would allow us to release meaningful customer value quickly?_
* GitLab integration using the same "development" sidebar
* Other plug-ins could integrate with the same sidebar, providing link to work items. E.g. my (imaginary) custom CAD design program which integrates links to work packages. That plug-in would allow us to link from a work package to my CAD files like we used to link to PRs.
* More OpenProject commands
* A "OpenProject" status PNG file to include in a PR description ([like many CI services do for their status badges](https://circleci.com/docs/2.0/status-badges/))
* Possible information to include could be:
* Deadlines (start date, end date)
* Linked work packages (e.g. when blocked by another work package)
* Context of other work packages based on the Gantt chart
# (Technical) Considerations
* We need to add support for the official GitHub API using GitHub Apps and the OAuth flow as webhooks alone don't allow us to create commits/PRs
* Optionally we could use [a solution like tickety-tick](https://github.com/bitcrowd/tickety-tick/) which copies a shell-command to create the branch/commit to the users clipboard.
* We could continue to use work package comments as the means of communication to save development time, but this would likely reduce the perceived customer value (less overview of the current state on GitHub).
* In this proposal the "development" sidebar is imagined to be part of OpenProject core (enabled with a project-option). This sidebar is filled by plugins for GitHub, and later, GitLab.
* This allows us to provide a core-infrastructure for development information and only specialize in the GitHub/GitLab-specific parts.
* Potentially, our existing Git integration could use the same sidebar.
* Potentially, we could integrate all sorts of app in that toolbar (e.g. CAT programs, other editors where "the real work" is done) and link items to WP's)
<figure class="image op-uc-figure" style="width:50%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/20479/content"></div><figcaption class="op-uc-figure--description">A preliminary data model for the GitHub integration</figcaption></figure>
# UI Prototypes
The following figma link contains some early UI prototypes. They are likely to need further discussion and grooming.
[https://www.figma.com/file/nOA3zyuP4FcARe4GJac0xQ/OP-GH-Integration?node-id=0%3A1](https://www.figma.com/file/nOA3zyuP4FcARe4GJac0xQ/OP-GH-Integration?node-id=0%3A1)
<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/20460/content"></div><figcaption class="op-uc-figure--description">Early UI prototype (figma screenshot) - showing the work package details view with the proposed work/development sidebar.</figcaption></figure>
# 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?_
* Project management, team collaboration and roadmap planning is done in OpenProject, but software development happens on GitHub.
* Developers need to manually synchronize state of their work 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` > `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 1: 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 2: Sync progress of a Pull Request with work package
* Given there is development progress on a PR, status transitions can be configured on a per-project basis that are applied to the linked work package
* The following GitHub actions can be configured:
* Draft PR is marked as "ready for review"
* A PR was merged
* A PR was closed without merging
* The OpenProject "development" sidebar shows the current status of any linked PR (draft, open, closed, merged) along with the GitHub user who created the PR
## Use Case 3: Link a manually created Pull Request to a work package
* It is possible to link PRs to a work package without using the "Create PR" button mentioned before by mentioning the ticket-code in brackets in a PR subject, a PR body, or a commit message. The work package code for a work package with the ID 3867 is `[#3867]`.
* Using this method, it is possible to link multiple PRs to a single work package
* We add a new instance-wide configuration setting to authenticate the OpenProject instance against a GitHub organization or user, using the ["GitHub App OAuth flow"](https://docs.github.com/en/developers/apps/authorizing-oauth-apps).
* We add
* This page also allows to configure state transitions on PR updates, see: "Use Case: Progress on a Pull Request"
> Workflows are the same in OpenProject throughout all projects. So I am wondring if we need to have different mappings on a project level.
## Use Case 5: Create links to OpenProject work packages in PR descriptions
* When a PR is created, edited or a new comment was added on GitHub, OpenProject scans the text for work package codes (e.g. `[#3867]`) and replaces these with links to the respective work package.
* This assumes a project is linked to the repository and the project has a work package with the mentioned ID.
# 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._
## Use Case: Additional work on a Pull Request
_This use case is considered an addition to the MVP, but was requested by AMG in a call on 2020-02-01._
* There is other types of work possible on Pull Requests than just status changes:
* A review was done (being a comment/approval/rejection) by a specific GitHub user
* A "check" (like CI/CD) was run with a state (success/error/pending) and a message (e.g. link to a test-platform)
* Ideally, we show that information (with a link pointing to the respective GitHub details page) in the development sidebar beneath the linked pull request.
## Use Case: Time logging
_This use case is considered an addition to the MVP, but was requested by an internal open project call on 2020-02-01._
* Developers are able to log time on a linked work package by writing an "openproject-command" , e.g.: `@openproject book_time 1h`
* Note: the actual syntax is subject to change (especially `@openproject` as this notation is already picked-up by GitHub to link against a GitHub-user named "openproject")
* times may be provided as of [the following regex `/\d+(\.\d+)?[mhd]/`](https://rubular.com/r/Pe1Q8iauJ55G2n) booking time for the given amount of minutes/hours/days (given an 8-hour work day). An openproject command must be the only text on its line.
* Note: This use case was briefly mentioned and filled-in by tessi, we need to check this against the reality of time booking in open project :)
## Use Case: Comments that should be synced from GitHub to OpenProject
_This use case is considered an addition to the MVP, but was requested by an internal open project call and an AMG call on 2020-02-01._
* Normally no GitHub communication is linked to OpenProject
* Developers are able to add a reference to the current GitHub communication thread to the linked work package by using an open project command \`@openproject mention\`
* Note: the actual command is subject to change (see "Use Case: Time logging")
* Once the command is noticed, a new comment appears on OpenProject which cites the GitHub message and links to it.
* GitHub messages that can contain this command are:
* PR descriptions
* PR comments
* commit comments
* commit messages
* review comments
## Use Case: Link OpenProject users with GitHub users
* When showing development updates in OpenProject, we usually show GitHub usernames. Ideally we could find a matching OpenProject-user to every mentioned GitHub-user and show the avatar/username of the OpenProject user.
## Use Case: Sync milestones between OpenProject and GitHub
* Both, GitHub and OpenProject, have a milestone feature. We may be able to sync milestones between them.
## Use Case: Configure scheme for default branch names and commit messages
* Not all work packages are targeting feature branches, thus their naming scheme for branches or commit messages may differ. Also, different project may have different naming schemes. It should be possible to adapt the default branch names / messages on a per-project bases.
## Use Case: See GitHub API Status
* Our API may be perceived as slow or buggy when GitHub has problems. We could fetch [the GitHub API status](https://www.githubstatus.com/api/#status) and display a warning message if webhooks or other APIs we use are impacted.
# Differentiation
_What do you believe will differentiate us from the current experience or competitive experiences?_
Comparison to the existing GitHub plugin
* Set-up of the current plugin is hard to do right (required a "GitHub" user and correctly places webhooks). This solution would automate the GitHub-facing configuration using the GitHub API.
* The current plugin only comments on PR changes (sometimes too often, e.g. when a PR is edited), these comments tend to get lost in long comment threads. Our solution provides a better overview by using a separate "development" sidebar tab
* The proposed solution is able to show more information of a PR than just it's state, e.g. CI/CD state or reviews
* The solution is extensible using more "openproject commands" on github
Comparison to the competition
* Showing the state of a PR and linking them to issues/tickets is a given for most mature project management software (Jira)
* Our feature of starting the work flow with default branches/messages is new ([there are existing OpenSource solutions working as browser plugins](https://github.com/bitcrowd/tickety-tick/))
# Next iteration
_What is the next solution that would allow us to release meaningful customer value quickly?_
* GitLab integration using the same "development" sidebar
* Other plug-ins could integrate with the same sidebar, providing link to work items. E.g. my (imaginary) custom CAD design program which integrates links to work packages. That plug-in would allow us to link from a work package to my CAD files like we used to link to PRs.
* More OpenProject commands
* A "OpenProject" status PNG file to include in a PR description ([like many CI services do for their status badges](https://circleci.com/docs/2.0/status-badges/))
* Possible information to include could be:
* Deadlines (start date, end date)
* Linked work packages (e.g. when blocked by another work package)
* Context of other work packages based on the Gantt chart
# (Technical) Considerations
* We need to add support for the official GitHub API using GitHub Apps and the OAuth flow as webhooks alone don't allow us to create commits/PRs
* Optionally we could use [a solution like tickety-tick](https://github.com/bitcrowd/tickety-tick/) which copies a shell-command to create the branch/commit to the users clipboard.
* We could continue to use work package comments as the means of communication to save development time, but this would likely reduce the perceived customer value (less overview of the current state on GitHub).
* In this proposal the "development" sidebar is imagined to be part of OpenProject core (enabled with a project-option). This sidebar is filled by plugins for GitHub, and later, GitLab.
* This allows us to provide a core-infrastructure for development information and only specialize in the GitHub/GitLab-specific parts.
* Potentially, our existing Git integration could use the same sidebar.
* Potentially, we could integrate all sorts of app in that toolbar (e.g. CAT programs, other editors where "the real work" is done) and link items to WP's)
<figure class="image op-uc-figure" style="width:50%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/20479/content"></div><figcaption class="op-uc-figure--description">A preliminary data model for the GitHub integration</figcaption></figure>
# UI Prototypes
The following figma link contains some early UI prototypes. They are likely to need further discussion and grooming.
[https://www.figma.com/file/nOA3zyuP4FcARe4GJac0xQ/OP-GH-Integration?node-id=0%3A1](https://www.figma.com/file/nOA3zyuP4FcARe4GJac0xQ/OP-GH-Integration?node-id=0%3A1)
<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/20460/content"></div><figcaption class="op-uc-figure--description">Early UI prototype (figma screenshot) - showing the work package details view with the proposed work/development sidebar.</figcaption></figure>
# 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?_