On this section we will explore how to contribute to the project with issues and pull requests.

Issue Labels

We use GitHub labels to categorize epics, issues and tasks. They are the foundation of our process, so please use labels for issues.

Labels are grouped. Each label consists of two parts: A Group and a Name which are separated by a slash (/). For example, the label module/ui is used to mark issue which is relevant to the Syndesis UI module.

The following label groups are available. There must be only at most one label from the “Exclusive” groups.

cat/Misc categories which can be added freely
prio/Priority of the issue. Only one prio/ label must be added per issue. prio/p0 is of highest priority, prio/p2 the lowest one.✔︎
ext/Reference to external projects
source/Where did the issue originate from (stakeholders)? i.e. source/qe indicates that QE raised this issue.
group/Internal Syndesis modules
notif/Notification label which can be added and removed to ping certain subteams
pr/Labels which are only relevant for pull request and which have also some semantics for the bot managing pull requests
size/Tee shirt size for issues. Sizing is a subjective assessment and should be done relative to other issues.✔︎
status/Status of an issue or PR.

Each label group serves a particular purpose, and for each issue and PR, it should be considered whether a label from a group applies.


Labels from this group reference our application groups like “rest”, “ui” or “connector”. Each sub-team is responsible for one or more group, and every group has an ‘owning’ team. That does not mean that members of other teams are not allowed to work on such groups. Contrary, this is even encouraged. But its just there so that teams can filter on issues and PRs which are relevant to them.

An issue can carry many group labels. Especially Epics will carry more than such label as they touch more than one group (otherwise it wouldn’t be an epic).

For Java code, a “group” roughly corresponds to a directory directly below app/.

group/commonSyndesis shared common module
group/connectorSupported camel connectors
group/extensionTools for developing Syndesis extensions
group/installInstalling Syndesis (templates, scripts)
group/integrationLibrary used in the the integration runtimes
group/metaService for connector meta-data and verification of connections
group/operatorInfrastructure operator related
group/s2iS2I base image for building integrations
group/serverREST backend for managing integrations
group/uiUser interface SPA, talking to the REST backend
group/uxdUser experience (UX) designs


Labels from the cat/ group are labels which can always be applied and which does not fit in another category. Currently we have these categories:

cat/bugA bug which needs fixing.
cat/buildFor issues which have relevance for the build system.
cat/designA concrete UX design. Use this for PRs containing UX designs.
cat/discussionThis issues requires a discussion.
cat/featurePR label for a new feature
cat/processDevelopment process related issues carry this label.
cat/questionFor issues holding a question.
cat/researchLabel used for issues which describe some research work
cat/starterAn issue which is easy to solve and can be used for ramping up new developers.
cat/techdebtLabel for issues identifying technical debt.
cat/techdocTechnical developer information (likes this handbook ;-) related issues.
cat/user-storyA user story, which might not be an epic

Pull Requests

This category of labels is all about pull requests. All of them have a meaning for the pure-bot bot which watches a pull request and performs certain action. These actions also involve monitoring and creating labels.

The following labels are involved:

pr/approvedThis label will be automatically applied to a PR as soon as the PR has been approved at the end of a review. It is an indicator for pure-bot to automatically merge the pull request if it passes all required tests. You should not set this label manually for approving a PR but using the GitHub button to do so.
pr/needs-backportThis pull request needs a corresponding backport to the latest patch branch.
pr/review-requestedIn our process it is not mandatory to have a PR review. However, if the author requests a review via the normal GitHub functionality, this label gets applied automatically. When this label is set on a pull-request, then the mandatory status check pure-bot/review-requested will only pass if at least a single pull request has been given, so prevents manual merging (without forcing).
status/wipThis is a PR request label which should be used for “Work-in-Progress” kind of PRs which has been submitted for early review. If this label is present on a PR, the PR is not merged, even when it is approved. A dedicated mandatory status check pure-bot/wip monitors this labels and prevents merging if this label is present.
status/1.4.xThis pull request is against the 1.4.x patch branch (analogous labels might appear over time)


Notification labels from the notif/ group serve a particular purpose. They are used when one team wants to notify another group that a specific issue might have them relevance to them.

notif/docThe issue needs some attention from the docs team. This might because a new feature has been introduced or, more important, an existing feature has changed for which a documentation already exists.
notif/pmThe issue needs input from product management.
notif/triageEvery new issue gets this label and is considered during a triage session for properly priorisation and categorisation. Remove this label after the triage has happened.
notif/uxdThis label should be used for issues which needs some attention from the UX team. This might because a new feature has been introduced or, more important, an existing feature has changed for which a UX design already exists.

It is important to note that these labels also be removed when the notification has been received.

For example, when a UI feature like an input form changes. Then the UI team attaches a notif/uxd label to the PR which introduces this change. The UX team, detects with a filter search on this label, that there is a new notification. It then decides, whether UX design needs to be updated or not. In any case, they are removing the notif/uxd label and add a module/uxd label if this PR indeed requires a UX design update. If no update is required, then the label is removed without replacement.


Labels starting with source/ indicate the origin of an issue. It should be applied to help in triaging and prioritizing.

source/qeThis issue has been raised by QE

External references

This label group should be used if an external system is referenced, which is not part of the Syndesis mono repo.

External ProjectDescription
ext/atlasmapatlasmap data mapper
ext/qesyndesis-qe suite
ext/docssyndesis-documentation End user documentation

For the future, we plan to add more of these external repos into the Syndesis mono repo (like documentation or QE). If this happens, then labels should be converted to module/ kind of labels.


Status labels are unique since they may trigger some automatic actions.

The current status labels are:

status/blockedThe current issue is blocked by another issue. Refer to the issue itself to see what is blocking this issued. This label is purely informal.

Issue Management and Communication

With Github as the primary tool for logging and handling issues, it is important to become proficient in utilising its interface and taking advantage of the extra tools available.

Displaying Issues

Issues can be displayed natively in Github by clicking the Issues button at the top of the main repository page. This provides a list of all the issues which can be filtered according to text, status etc.

Have a look at how to find information in a repostiory on GitHub help. For example to show only issues that one is assigned to, the filter is:issue is:open assignee:@me can be used.

Correspondingly, for pull requests pull requests awaiting ones review can be found using is:pr is:open review-requested:@me filter.

Being Notified of Issues

Once assigned to the project, the registered email address should being receiving notifications from Github concerning any modifications to any issues. This can quickly fill an inbox so filtering these into their own folder is recommended (a new developer can expect to see 50-100 per day). Additional tools, like Octobox or the new GitHub Notifications (currently in beta), are available for helping with managing these notifications so please ask other project members if you are struggling to handle them.

Administering Issues

Issues are the bedrock of the project and provide the window into understanding what each developer is currently working on. Therefore, it is important to log issues, assign issues and provide comments to issues. Github provides tools to connect issues and Pull Requests (PRs) and even if the PR does not require an issue (rarely!) then it should be possible to provide sufficient context in the PR that spells out its nature and relevance.

Once assigned, an issue is your’s to log as much detail as required to portray any problems, difficulties or solutions. Should you need help then Github provides syntax using the @UserName syntax to prompt other’s to comment on the issue. Given the plethora of notifications that developers receive on a daily basis, it is recommended to use this syntax if you require additional input, since this sends additional notifications specifically asking the developer concerned to comment. In the event that you are unsure who to contact then it is not impolite to include a number of @UserNames in the issue and someone will respond and either reply directly or in turn notify a person who can. Everyone understands the importance of collaboration so speaking up is to be only encouraged.

Closing Issues

Development is about solving the issues and closing them down. Therefore, closing issues is a good thing. Do not be afraid to close an issue if the problem has been solved or indeed if the problem has gone away on its own (yes this does happen!). In the event. that a code change has occurred and a PR submitted then that PR will have been reviewed by another developer. There may be a back-and-forth in comments and requests for changes but finally the PR will be approved by the reviewer. Once that happens, the PR will be automatically merged and closed. If an issue is directly linked to the PR then that too will be closed as well. Should this not be required then the issue can of course be re-opened. Once the issue is closed then it is back to the dashboard to find a new one!

Still Having Trouble?

Ask on Gitter