Content
Updated by Philipp Tessenow over 3 years ago
# Out of Scope for the MVC <mention class="mention" data-id="36132" data-type="work_package" data-text="#36132">#36132</mention> data-text="#36132">#36132</mention>
_What should NOT be in the minimal viable change, and can be considered for future iterations? Why? Please order them by importance._
## _Use Case:_ GitHub <-> WorkPackage status synchronization
* 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. We could automatically advance work packages depending on their PR state (potentially with configuration options)
## 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._
* 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.
* `tickety-tick-formatter` allows us to use (project-specific) templates for default branch names and commit messages. We could use that instead of relying on the built-in default templates to customize our commit messages and branch names.
## 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.
## Use Case: Set-Up the GitHub plug-in
* 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)
# 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 approach.
* 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
# 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)
_What should NOT be in the minimal viable change, and can be considered for future iterations? Why? Please order them by importance._
## _Use Case:_ GitHub <-> WorkPackage status synchronization
* 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. We could automatically advance work packages depending on their PR state (potentially with configuration options)
## 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._
* 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.
* `tickety-tick-formatter` allows us to use (project-specific) templates for default branch names and commit messages. We could use that instead of relying on the built-in default templates to customize our commit messages and branch names.
## 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.
## Use Case: Set-Up the GitHub plug-in
* 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)
# 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 approach.
* 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
# 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)