UPDATE: August 2018
Partnering with GitLab
After the first four installments of our blog series it looked as though we were on a path to implementing BitBucket for our code collaboration tools. However, after an out pouring of feedback from the community and several months of close collaboration to clear blockers, we're happy to announce a change of plans: We will be migrating our development tools to GitLab.
This is the third post in our series about integrating Drupal.org with a 3rd party developer tooling provider:
- Where we stand now, and our evaluation criteria.
- The options we considered.
- An illustration of what Drupal.org integration with a 3rd party tooling provider could look like.← you are here
- A possible implementation plan for this initiative.
- Announcing our migration
Below are some rough mockups of what a modular integration between Drupal.org's issue queues and a third party toolset could look like. For the sake of this example, I've used Bitbucket as the tooling provider, as that is likely to be our interim toolset for the reasons outlined above. However, one can easily imagine these functions being substituted for their equivalents in other toolsets.
The following is only an early concept. These are by no means final designs for each of these integration points, but they will help to visualize how these tools will be integrated with Drupal.org.
Mockup: Workspaces in the issue summary
The biggest change for contributors would be the addition of a new place in the issue summary to contain these workspaces. For most issues we anticipate a single workspace, as most issues are resolved via collaboration on a single code path, however we would be able to generate multiple workspaces per issue for multiple solutions being proposed in parallel:
The key functions of the Proposed code workspace are: the ability to make a new workspace, the ability to clone an existing workspace, the ability to create/view/edit a workspace merge request. The latest test result and ad-hoc testing options for each workspace would be provided here as well.
Mockup: Propose new Code
The "Propose new code" button is very simply a way to automatically generate a new workspace. This would only be used when a contributor wants to propose an alternate solution to whatever is currently under development. When pressed, we would generate a new workspace with the back-end tooling provider (whether as a fork, branch, or Git namespace) and add it to the table to be cloned, viewed for comments/inline editing, or ultimately to create a new merge request.
The new workspace will be generated with a name based on the issue id, and will present its own test result, clone, and merge request features.
If a user wants to collaborate on an existing solution instead, they can simply clone that workspace locally, or view it to make inline edits. Because some issues can languish for months, or even years, we also want to automate the process of rebasing these workspaces from their parents.
Mockup: Automatic comments as workspaces are updated
Whenever a change is made within the third party toolset, we would use the API to call back to Drupal.org and leave a system message describing the change, as well as linking to the relevant part of the third party toolset UI.
This is what an automated issue comment for code review might look like:
This is what a comment for recently pushed changes would look like:
And this is what a comment for inline edits could look like:
Mockup: Clone
The clone button would simply provide a basic modal pop-up with instructions for collaborators to clone the workspace locally with Git. This is not the final url pattern (one of our goals is to avoid changes in canonical git urls where possible) but it could look something like this:
$ git clone ssh://git@bb.drupalcode.org/is/drupal.git
Mockup: Create Merge Request (in Bitbucket)
Merge requests allow contributors to propose changes to projects they don't maintain, and provide maintainers an easy way to view proposed changes.
The create merge request button would allow the user to view the current workspace and request that it be merged into the canonical parent. Only a project maintainer would have the permissions to complete the merge.
Code in a workspace with an open pull request can continue to be iterated on by the contributors. Code comments, diffs, and reviews are summarized on the request.
Mockup: View Merge Request (in Bitbucket)
View merge request, like 'create merge request' would allow any collaborator to view the current workspace. This could also be used to initiate inline code edits, or leave code comments.
Mockup: Inline editing
Inline editing allows a quick and easy way for people to propose "standalone" changes to e.g. documentation, markup, etc. without having to have an entire development stack.
We would rely on the third party tooling provider's inline editing functionality. In the example below, we can see how an inline edit is made using Bitbucket:
Mockup: Code review
As with inline editing, we would rely on the third-party tooling provider's tools for code review. In the example below you can see the code review options provided by Bitbucket:
As indicated above, these mockups are simply an illustration of what this integration could look like, not final designs. However, this has hopefully shown how we can introduce a hybrid model to integrate the best features of a third party tooling provider (pull requests, code review, inline editing), while retaining the essential nature of the drupal-flow.