Home
This document will describe how to use Topcoder-X as a copilot.
- Site: https://x.topcoder.com
- Dev site: https://x.topcoder-dev.com
Topcoder-X is an application that allows a copilot or Topcoder customer to manage work directly through Gitlab or Github. When an issue is created in a Gitlab or Github project set up in Topcoder-X, Topcoder-X will create a Topcoder challenge to mirror the Gitlab or Github issue, and it will ensure that the challenge has the correct prize, copilot, assignee, description, and title.
As the Gitlab or Github issue is updated, Topcoder-X will ensure that the Topcoder challenge associated with the issue is updated appropriately. When the Gitlab or Github issue is closed, Topcoder-X will activate and close the Topcoder challenge, ensuring that the members (submitter and copilot) get paid as expected.
Topcoder-X monitors Gitlab and Github repositories, looking at issues created. Gitlab and Github repositories will need to be configured with a webhook callback for Topcoder-X so that Topcoder-X is "aware" of changes made to issues on a repo. Topcoder-X can create this webhook for you.
When Topcoder-X performs specific actions to the Topcoder challenge that is associated with a Github / Gitlab ticket, Topcoder-X will create comments on the issue in Github / Gitlab explaining the update and where to find the Topcoder challenge.
When you first login to Topcoder-X, you will see a screen like this:
Topcoder-X first needs to know about your Github and Gitlab username. It will use this to map your Github and Gitlab user to your Topcoder handle, as well as make comments to issues on your behalf on Gitlab and Github.
- Click your username in the upper right
- Select
Settings
You will now see a screen where Github and Gitlab can be setup:
Click Setup for both Gitlab and Github and authorise Topcoder-X to have access to your repo.
Once done, you should see checkmarks next to both Gitlab and Github.
A project in Topcoder-X maps a Topcoder Direct project ID to a git repo. When you first launch Topcoder-X, you won't have any projects set up:
You can set up a project by clicking Add a Project on the Project Management tab.
-
Project Name- Anything you want to use as the project name. This can be anything memorable -
Direct ID- This is the Topcoder Direct ID for the project. This should be a 5 digit number. You can retrieve this by pulling theprojectIdvalue from the end of the URL when you visit the project in Topcoder Direct. For example:https://www.topcoder.com/direct/projectOverview?formData.projectId=17159has aDirect IDof 17159 -
Repo URL- This is the URL to the repository in either Gitlab or Github. This should be the link to the actual repository that houses code. This is not the group or parent of the repository.
Here's an example:
Once a repository has been added as a project, you can see it in the list of current projects.
You can click the Edit button for a project to go to the Edit a Project screen
On the Edit a Project screen, you will see three buttons:
Add LabelsAdd WebhookAdd Wiki Rules
Add Labels
The Add Labels button will add a default set of labels to either a Gitlab or Github repository. These labels can be applied to tickets to indicate different states of a ticket.
The labels added are:
tcx_OpenForPickuptcx_Assignedtcx_FixAcceptedtcx_Paid
Add Webhook
When Add Webhook is clicked, the webhook callback will be automatically added to the Gitlab or Github repository. This webhook is called whenever an issue is updated on the repository, ensuring that Topcoder-X is "aware" of the changes made in real time. Topcoder-X will ignore any projects that don't have a webhook set up properly
Add Wiki Rules
Clicking Add Wiki Rules will add a new wiki page to a Gitlab project called Gitlab ticket rules. This new wiki page will describe to members how to assign and work on Git tickets. Note - for Github, an issue will be created, not a wiki page, due to limitations in the Github API. The content is the same for both Gitlab and Github.
A current project is one you are working right now and that is active for members to be able to access. We prioritize those in the UI. An archived project is one that isn't currently active for members or that has completed. Archived projects are still available in the UI, for historical purposes, but they aren't currently monitored by Topcoder-X. A project can be moved from current to archived and back again without any side effects. You can edit whether or not a project is archived using the Archived checkbox on the Edit a Project screen.
One of the quirks of Topcoder-X is that most members have different usernames between Github / Gitlab and Topcoder. We have to have a mapping of a user's Github / Gitlab username to their Topcoder handle to ensure that payments process correctly. We also need a way to ensure that members can gain access to repositories automatically, without a copilot or PM having to grant explicit access to each member.
The Git access control link on the left side menu handles both the mapping and access grant functionality.
For each team in Github and Gitlab there will be a Get Link button that will generate a URL that can be shared to members. If you're familiar with Ragnar, this is the same idea, but specific to Topcoder-X.
When a member accesses this link, it will take them through two flows:
- Authorization of Topcoder-X for either Gitlab or Github, depending on the team type
- Authorization to Topcoder to gain their member details
The flow will:
- Grant the user access to the git group (assuming the copilot / PM has
ownergroup access) - Add a user mapping into the Topcoder-X database so that the system can map between different user account names
For each repository / project, you should have the members that need to work on the project use the Topcoder-X Git access control link. This will ensure that their accounts are properly set up in the system to allow for automatic payments, and it will also ensure they have access to the necessary code location.
For this to work, you need to have a reasonable team setup, so please plan your teams appropriately. For instance, if a project involves both a backend and a front end and they are split into separate repos, they should both be under the same Github / Gitlab team, instead of under separate teams.
Once a repository has been set up as a project, we can start to open tickets up for members.
An issue on Github / Gitlab can be created in a repository. The title should be in the format [$<payment amount>] <This is the title of the ticket>
An example would be: [$40] Update the button colors from green to blue
Topcoder-X will parse out the [$40] text and will use that to set the payment amount on the Topcoder challenge appropriately.
When a ticket is created, the initial label should be tcx_OpenForPickup
When a ticket is created, Topcoder-X will:
- Parse out the ticket details, including the title, description, and payment amount
- Create a new Topcoder challenge in the Topcoder Direct project set up for this particular repo
- Post a new comment to the git issue with a link to the Topcoder challenge
Example:
Members will see that the ticket has been created and labeled as open for pickup. When a member decides they want to work on an open ticket, they will:
- Assign the ticket to themselves
- Remove the
tcx_OpenForPickuplabel - Add the
tcx_Assignedlabel
Topcoder-X will handle the assignment event and will update the Topcoder challenge to be assigned to the member whose Topcoder handle matches the Gitlab / Github username currently assigned. The member is required to use the Git access control link described above first to ensure their username is properly mapped.
A new message will be posted back to the git issue comments explaining that the challenge has been assigned:
The member will work on the ticket, asking questions, and will create a merge request. The member should then add the label tcx_ReadyForReview to alert the copilot that the ticket can be reviewed.
If the copilot has issues with the ticket they would like to see changed, they should remove tcx_ReadyForReview and add label tcx_FailedCodeReview and tcx_Feedback. They also need to post a clear comment explaining why acceptance failed and what further changes are necessary.
If the fixes look good, the copilot has to add label tcx_PassedCodeReview.
The Architect will complete a PR merge for tickets with tcx_PassedCodeReview. Once it is merged onto a dev environment, Architect will add label tcx_ReadyforQA, which QA will pickup to test.
QA will add labels tcx_FailedQA and tcx_tcx_feedback if it does not pass QA to notify the Copilot that the ticket needs to be reviewed.
Or QA will add label tcx_PassedQA to notify the Architect to PR to Master. Once the Architect merges code to the Mast branch, he will add label tcx_ReadyforQAinPROD. QA will do final test in PROD environment and if it passes, QA will add labels tcx_PassedQAinPROD and tcx_FixAccepted and close out the ticket. Or QA will add label tcx_FailedQAinPROD to notify Architect to check for merge issues.
NOTE: If the ticket is closed without the tcx_FixAccepted label, no payment will be processed for the ticket. A warning will be added as a comment to the Git issue explaining that no payment will be processed until the tcx_FixAccepted label is added. You can keep the label off if you want to close a ticket but don't want it paid for some reason.
When a git issue is closed, Topcoder-X will do the following:
- Activate the Topcoder challenge assigned with the git issue
- Add the copilot to the challenge
- Close the challenge, with payment to both the copilot and submitting member
- Change the labels on the git issue to:
tcx_Paid,tcx_FixAccepted - Add a comment explaining that the Topcoder challenge has been updated
The Dashboard link in the Topcoder-X UI contains a tabbed array of tables that can be used to view the status of tickets across all projects set up with Topcoder-X for a given user. This is a good, easy way to get the status of various tickets "at a glance". As each ticket's label is updated, it will move from the Open for pickup tab to Assigned to Ready for review to Paid. The tables on Dashboard aggregate all tickets across all projects set up under Project Management.
If a Github / Gitlab ticket has problems, you can use the Recreate an issue button on the Manage a Project page to recreate the Topcoder challenge associated with the ticket.
This can be useful if:
- The Topcoder challenge isn't processing correctly for some reason
- The Topcoder challenge associated with the Github / Gitlab ticket never created successfully when the ticket was opened.
To use, just paste the URL of the Gitlab / Github ticket into the Issue URL box, check Recreate and then hit OK. The issue should then get reprocessed and a new Topcoder challenge created.
Topcoder-X can track payments for copilots that fall outside the scope of normal challenge payments for a challenge or F2F. This could be anything from client phone calls to requirements gathering or additional testing / validation work for a project.
To add a copilot payment, click the + Add Payment button. You will see a form.
- Project - the project that will be associated with the payment. This is important because the Topcoder Direct ID associated with the Topcoder-X project is used to get the billing code assigned to the copilot payment
- Amount - A numerical value that indicates how much the payment should be for
- Description - A text description of the payment, like
Client phone call on Sept. 21st, 2018.
A copilot challenge will be associated with each project at any one time. So, if you create 3 separate copilot payments for a single project, they will be lumped together as one Topcoder challenge. The description of the challenge will list the amounts and descriptions for easy tracking:
The copilot should not close the payment ticket directly. Instead, email your PM with the link or links to the individual copilot payment tickets and have them close it out, after they have reviewed it. This can normally be done on a regular interval, like once a week or once a month.
Once a ticket has been closed in Topcoder Direct, click the Refresh button in Topcoder-X to clear the copilot payment table and show the current state.
