1
0
Fork 0

Improve README and Add Licence

Summary: Improve the README giving an overview of the project and why it was needed. Also add the MIT licence since we are going to open source the plugin and credit the orginal author the Harbormaster files we are using. Also updated the TeamCity build definition to include build number in the plugin output file.

Test Plan:
Packaged locally to verify the version number is included in the plugin zip.
Other changes were text in the README and LICENCE

Reviewers: #dev, rob.marshall

Reviewed By: #dev, rob.marshall

Subscribers: rob.marshall

Differential Revision: https://phab.xlab.uk/D2704
This commit is contained in:
Steven Cooney 2019-06-21 09:29:03 +01:00
parent 694b6413ee
commit d99cf09270
7 changed files with 90 additions and 31 deletions

22
LICENSE.txt Normal file
View file

@ -0,0 +1,22 @@
The MIT License (MIT)
Copyright (c) 2015 Matthew J Oliver
Copyright (c) 2019 X-Lab Ltd
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

View file

@ -1,51 +1,91 @@
# Splint
_X-Lab's Linting Spine_
# Teamcity-Phabricator-Plugin
Connecting Phabricator and TeamCity to run builds with changes from code reviews and report the results.
## Things
This repository holds the plugins created to link together our internal systems. The original premise to link Phabricator, TeamCity and SonarQube to enable linting on differential reviews.
## Plugins
Below are the plugins:
* Harbormaster-Teamcity-Plugin
* Teamcity-Phabricator-Plugin
* SonarQube-Phabricator-Plugin
There are two plugins that work hand-in-hand to enable TeamCity builds with changes from a Phabricator code review. If you are unfamiliar to [Phabricator](https://www.phacility.com/phabricator/) and their terminologies see the **Background** section below for an overview.
### Harbomaster-Teamcity-Plugin
**Harbormaster-Teamcity-Plugin:**
An extension to Phabricator to enable triggering of builds within TeamCity using Harbormaster.
**Teamcity-Phabricator-Plugin:**
A TeamCity plugin that patches in changes from a Phabricator code review and reports the build status back to Phabricator.
## Background - Phabricator Workflow & Terminology
The Phabricator Software Development Suite has the ability for code review, CI & CD along side numerous other development tools.
Phabricator code reviews are called [_Differential Revisions_](https://www.phacility.com/phabricator/differential/). Phabricator differs to other code review workflows because they are pre-commit reviews and therefore the changes that are getting peer reviewed are not in version control. This gives Phabricator a _write_, _review_, then _merge_ workflow, which is different than most pull-request methodologies such as GitHub. In this workflow our code changes are managed by Phabricator and are not in version control during the code review process for us to build with CI.
To trigger a _Differential Revision_ (code review) a command line tool called [_Arcanist_](https://www.phacility.com/phabricator/arcanist/) is used. This tool handles the interaction with Phabricator to request, update and merge code reviews. An example of putting code up for review would be running _Arcanist_ like: `arc diff`. This would essentially mimic pushing a feature branch and creating a PR. If another developer wanted to pull down a copy of the changes to review in-depth they would also use _Arcanist_ to patch in the changes: `arc patch <Differential ID>`.
When a _Differential Revision_ is created, Phabricator has the ability to to trigger CI "builds" with the changes, this feature is called _Harbormaster_. These _Harbormaster_ builds usually trigger other build systems which report back the results, one of the in-built triggers is for Jenkins. There is **no** inbuilt trigger for TeamCity.
## Why TeamCity Phabricator Plugins
As outlined above, Phabricator does not have a default trigger for TeamCity. To add a TeamCity trigger we have extended Harbormaster with `Harbormaster-Teamcity-Plugin` which adds the relevant files to communicate with TeamCity to run build configurations. The plugin also sends additional information to TeamCity for the partner plugin to use when reporting the result back to Phabricator.
Since code review changes are not in version control we cannot rely on TeamCity to patch in the changes using Git. We needed to create a plugin that listened and identified builds triggered by `Harbormaster-Teamcity-Plugin` and then utilise _Arcanist_ to patch in the exact changes that need to be built before reporting the result back to Phabricator.
## Installation
### Harbormaster-Teamcity-Plugin
The harbormaster plugin allows us to trigger a build configuration within TeamCity as part of a harbormaster build plan.
The plugin requires:
1. TeamCity URI
2. Build Configuration to trigger a build for
3. TeamCity access token to authenticate with the server
To deploy simply copy the contents of the `Harbormaster-Teamcity-Plugin` folder in to `src/extensions/` on the Phabricator instance and then restart the application. Currently there are only three files that need to be transfered: `HarbormasterTeamCityBuildStepImplementation.php`, `PassphraseTokenKey.php` & `TeamCityXmlBuildBuilder.php`.
To deploy simply drag the contents of the folder to `src/extensions/` on the Phabricator instance and then restart the application.
The Harbormaster build trigger requires:
1. TeamCity URI: The URL to your TeamCity instance
2. TeamCity Build Configuration ID for the build differential revision changes should be applied
3. TeamCity Credentials: A TeamCity REST API token to authenticate with the server stored within Phabricator's _PassPhrase_ feature.
![Harbormaster Build Step Configuration](./docs/Harbormaster_Build_Step.png)
### Teamcity-Phabricator-Plugin
The teamcity plugin comprises of server and agent plugins for teamcity.
The TeamCity plugin comprises of server and agent plugins for TeamCity. Together they collate the information sent from `Harbormaster-Teamcity-Plugin` and run _Arcanist_ to pull in the changes from the associated _Differential Revision_.
#### Server
The server plugin monitors builds with the phabricator feature enabled waiting for builds to finish and notify phabricator.
To deploy, upload the `Teamcity-Phabricator-Plugin-<version>.zip` on TeamCity's plugin administration page.
Once build is triggered from phabricator using **Harbomaster-Teamcity-Plugin** and the phabricator build feature is configured on the build configuration then the server plugin will wait and listen for the build to finish before reporting the result back to harbormaster to be displayed in phabricator.
This will install the **Phabricator Plugin** build feature that can be enabled per build configuration used for _Differential Revisions_.
## Getting Started
![Phabricator Build Feature](./docs/Build_Feature.png)
**Harbormaster-Teamcity-Plugin**
No building is needed for for the harbormaster plugin just dev away and copy the files into the `src/extensions` folder with your phabricator instance
The plugin requires `Harbormaster-Teamcity-Plugin` to be installed on Phabricator and the following to be configured in the TeamCity build feature:
**Teamcity-Phabricator-Plugin**
1. Phabricator URL: The URL to your Phabricator instance
2. Conduit Token: A Phabricator API token related to a user (should be a Bot user to follow best practices)
3. Path to Arcanist on the build agents. (In future we will remove the hard-coded path and look on the path for `arc`)
![Build Feature Properties](./docs/Build_Feature_Properties.png)
## Development
### Harbormaster-Teamcity-Plugin
No building is needed for the harbormaster plugin just dev away and copy the files into the `src/extensions` folder with your Phabricator instance.
### Teamcity-Phabricator-Plugin
You will need to move in to the `Teamcity-Phabricator-Plugin/` folder:
* To build the plugins (server and agent) just run: `mvn package`
* To build the plugins (server and agent) just run: `mvn clean compile package`
By default the teamcity plugin is equipped with teamcity-sdk-maven-plugin which allows for a local instance of teamcity with debugging capabilities. See their documentation for how to use: https://github.com/JetBrains/teamcity-sdk-maven-plugin
By default the TeamCity plugin is equipped with `teamcity-sdk-maven-plugin` which allows for developing against a local instance of TeamCity with debugging capabilities. See their documentation for how to use: https://github.com/JetBrains/teamcity-sdk-maven-plugin
## Useful Links
## Future Development:
* Look for _Arcanist_ on the path rather than hard-coding it.
* Report back unit tests
## Credits
The inspiration for the plugin is from https://github.com/halfmatthalfcat/TeamCity-Phabricator-Plugin which is no longer maintained. We have reused the Harbormaster files from the original authors repository.
## Some Useful Links
A collection of useful links that help when diving into TeamCity plugin development:
* https://confluence.jetbrains.com/display/TCD10/Web+UI+Extensions
* http://javadoc.jetbrains.net/teamcity/openapi/current/jetbrains/buildServer/serverSide/BuildServerAdapter.html
* http://javadoc.jetbrains.net/teamcity/openapi/current/allclasses-noframe.html
* https://github.com/JetBrains/teamcity-sdk-maven-plugin/wiki/Developing-TeamCity-plugin
* https://www.quali.com/blog/teamcity-plugin-development-journey/
* https://plugins.jetbrains.com/docs/teamcity/plugin-development-faq.html

View file

@ -89,7 +89,7 @@
<goal>single</goal>
</goals>
<configuration>
<finalName>phabricator-plugin</finalName>
<finalName>Teamcity-Phabricator-Plugin-${teamcity.phabricator-plugin.plugin.version}</finalName>
<outputDirectory>${project.parent.build.directory}</outputDirectory>
<appendAssemblyId>false</appendAssemblyId>
<descriptors>

View file

@ -5,12 +5,9 @@
<display-name>Phabricator Reporter</display-name>
<version>@Version@</version>
<description>Reports the status of Harbormaster trigged builds</description>
<download-url>Plugin download URL</download-url>
<email>Plugin author e-mail</email>
<vendor>
<name>@VendorName@</name>
<url>@VendorURL@</url>
<logo>Plugin vendor logo URL</logo>
</vendor>
</info>
<deployment use-separate-classloader="true"/>

BIN
docs/Build_Feature.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 10 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 16 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 28 KiB