Content
View differences
Updated by Niels Lindenthal about 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, issue tracking and roadmap planning is done in OpenProject, but software development and continuous integration happens on 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.
* 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)
## Pain
_What is the primary workaround that users perform that we could remove or replace? Why is it painful?_
* Starting point for a developer is a prioritized and scheduled work package in OpenProject. Before Befor developers can start programming they need to do a lot of manual setup tasks:
* 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.
* Developers need to manually sync the state of a work package with the the PR progress (`Draft PR created` > `Ready for review` > `closed || merged`). Very often the status is not synced which leads to confusion and errors.
* 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?_
**Summary**: We automate the workflow of synchronizing state between GitHub and OpenProject. At the same time we strive to keep information intended for application-specific use cases in their specific apps. For example, we 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: Automatically create a linked Pull Request from on a work package
* As a developer, I can open a work packages details page to find a new "GitHUb" 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 "GitHub" 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.
## 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 new configuration 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".
## 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._
* Please see ##36207 for further ideas
# (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)
* A preliminary data model for the GitHub integration
# 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)
## 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, issue tracking and roadmap planning is done in OpenProject, but software development and continuous integration happens on GitHub.
*
*
* 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)
## Pain
_What is the primary workaround that users perform that we could remove or replace? Why is it painful?_
* Starting point for a developer is a prioritized and scheduled work package in OpenProject. Before
* 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.
* Developers need to manually sync the state of a work package with the the PR progress (`Draft PR created` > `Ready for review` > `closed || merged`). Very often the status is not synced which leads to confusion and errors.
* 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?_
**Summary**: We automate the workflow of synchronizing state between GitHub and OpenProject. At the same time we strive to keep information intended for application-specific use cases in their specific apps. For example, we 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: Automatically create a linked Pull Request from on a work package
* As a developer, I can open a work packages details page to find a new "GitHUb" 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 "GitHub" 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.
## 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 new configuration 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".
## 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._
* Please see ##36207 for further ideas
# (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)
* A preliminary data model for the GitHub integration
# 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)