Skip to content

GitLab

O
ops
Last edited by bgm
Page history

gitlab roadmap

History & context

Early experiments using Gitlab (lab.civicrm.org) started around March 2017, as a tool to help with managing CiviCamps and the civicrm.org website, followed by the infrastructure issues, marketing, etc. The initial intention was to provide a collaboration space for areas that didn't fit in JIRA/Confluence. People often resorted to using direct emails with many CCs/forwards, since it was hard to know who was responsible for what.

As an experiment, we let Gitlab grow organically as a sort of beta service, collecting feedback. Initially, replacing JIRA was not on the table. Gitlab seemed to be a good candidate for replacing a lot of the left-over content of Confluence (after the migration of dev/admin documentation to mkdocs) and tracking non-core issues.

In November 2017, we reached a point where we had to re-evaluate what to do with JIRA, whether Gitlab could help with the extensions ecosystem, and how Gitlab can help the larger CiviCRM community.

What's wrong with JIRA?

  • We only use a fraction of the features of JIRA
  • JIRA tends to be overly complicated for what we do with it
  • It's not user-friendly, even to most developers
  • It's difficult to host & maintain
  • It's proprietary and also requires managing plugins with their own licenses
  • It's slow.

As a result, JIRA tends to be used only for the issue title, brief description, "affects version" and "fix version". Most of the discussion happening on the Github pull-requests. With few people using JIRA, it has become difficult to discuss feature improvements, triage issues, prioritize by community interests.

See also:

Process / Roadmap

We have been reaching out to developers, users, partners, members to ask about what works and what can be improved. You can see the roadmap in infrastructure/gitlab#2 which includes bits on how the discussion evolved. Our plan is to come up with a final roadmap by February 2018 at the latest. While we have not made formal announcements about JIRA yet (as of December 2017), we have been documenting the process and raising awareness in various spaces/channels/lists/sprints/camps, gathering feedback as we go.

The roadmap is in: infrastructure/gitlab#2

Feature requests & specs

Since December 2017, new projects have been created under the Development Team group in Gitlab:

These groups can help move forward discussions from the dev mailing-list, transforming ideas into tangible steps forward. They also help bridge the gap between Stack Exchange and Pull-Requests (which used to previously be either on the old forum or on JIRA).

Further discussion is slowly going towards a consensus that instead of having one monolithic issue tracker,

  • We could track issues directly in the dev-team sub-projects
  • Feature requests can be moved from one project to another, and it makes it easier to track priorities/roadmaps per component (ex: the projects listed above)
  • We can also share Gitlab issue labels between projects (ex: for critical/blocker issues)

While this could be done in JIRA, it required complicated dashboards. Very few people were comfortable using them. Gitlab makes discovery easier.

This structure can also help with funding feature requests. For example:

  • A group of people might create a set of feature requests for improving reporting
  • Gather feedback from the community by having upvotes on issues
  • If there is enough positive feedback, create a "Make it Happen" (MIH) campaign
  • Nag people who upvoted the issues, to participate in funding, implementation, testing.
  • No need to duplicate specs in various spaces (wiki, google-doc, etc). The issues may serve as meta-issues (with items split off in sub-issues) or be used directly to track the implementation.

Extensions

This has not been formally discussed with the Extensions WGs, brainstorm only!

Possible use of Gitlab for Extensions:

  • Provide vendor-neutral spaces for extensions,
    • as a way to encourage collaboration between shops (similar to drupal.org projects),
    • make it easier to transfer the maintenance of an extension to someone else if the extension is abandoned by its author.
  • Provide a central point where all official extensions (available automatic distribution) are available (Drupal/WordPress have similar policies).
  • Provide continuous-integration (CI) for extensions (this can also be done with Jenkins, but it requires more duct tape).

Translation

https://lab.civicrm.org/development-team/translations/

Security

  • Security issues can be handled in a private Gitlab project (currently issues are in non-public JIRA issues).
  • Possibility usable for security-related pull-requests (which Gitlab calls merge-requests), but could require changes to the continuous-integration.

Google Summer of Code

https://lab.civicrm.org/community-team/gsoc2018/

Structure and tags

While we hope to keep Gitlab fairly organic and allow for some experimentation, some elements have been mentioned a lot, so they might be worth documenting up front.

Issue labels common across all projects

  • critical (important for triage, to search across projects)
  • major (same as above)
  • feature (feature-request)
  • feature-postponed (closed feature request, might be re-opened later, so it might be important to track separately when we close it, since gitlab does not have a "wontfix" status)
  • ?

Groups and projects

Ideally the groups should somewhat reflect the Teams and Working-Group structure, but there can be some exceptions where it makes sense (better visibility, structure, etc).

  • Core Team (internal to the Core Team)
  • Community Team (ex: GSoC, webinars)
  • Development Team (all projects related to core code)
  • Marketing Team (ex: civicamps, website)

but also:

  • Documentation (docs.civicrm.org)
  • Extensions
  • Infrastructure (sysadmin things for running CiviCRM.org and other tools)
  • Security (CiviCRM security issues, kept private)

Frequently asked questions (FAQ)

How one would search to find if an encountered problem was a known issue, an issue being addressed, etc.?

"It would really help if a non-developer, non Github user could get some sense of how to use the proposed repository and, specifically, how one would search to find if an encountered problem was a known issue, an issue being addressed, etc." (@dtarrant)

The proposed Gitlab structure would be to have project spaces around components/themes of CiviCRM (financial, cloud-native, translation, reports, etc, but there would still be a "core" project).

This would aim to create somewhat more manageable spaces where teams can prioritise within those spaces). We can also search across projects in Gitlab.

It might also be necessary to also search the pull-request queue on Github, in case someone directly opened a pull-request.

Splitting issues across projects might be confusing? Triage?

Main issue: #823

"We cannot expect our users to have to understand the internal workings of CiviCRM in order to choose where they need to file their bug report." (@cividesk/Nicolas)

"Note that if easy to move issues around projects in GitLab, we might resolve end-user reporting of issues through an external, non-authenticated form collecting basic info on the issue (and reporter), which would then create an issue in the 'triage' project in GitLab. The issue would then be triaged and moved to the appropriate development project by technical contributors." (@cividesk/Nicolas)

"Is there any type of structure proposed for entering issues? Key words, categories, etc. A form?" (@dtarrant)

"The ability to apply multiple labels/tags, to indicate which components an issue relates to, provides a more flexible classification system than having to create an issue in one of a number of projects." (@davej)

This seems to be one of the issues that has been raising a lot of concerns. It does require more clarification.

So far, quick recap:

  • Subprojects can share labels, and we can search issues across subprojects
  • We could have a special process to triage new issues, such as having a front-end form.
    • Although we need the reporter to have a Gitlab account in order to receive the responses.
    • It might be better to focus on having a very clear signup process.
    • Spam management is also an issue.
  • Some issues might span multiple subprojects (ex: bug in a token included in a contribution receipt for an event).
    • Seems OK for triage folks to move the issue to the appropriate subproject.
    • It doesn't seem to be like a major problem. If critical, it will be labelled as such. We could have a policy to "default to core" when it's not really clear.
  • What do we gain from splitting the projects?
    • It helps more clearly identify who are the primary leads for a specific area. We have been talking about having a google-doc with "people to ping for PR-review".
    • Example: translation, civicase, grant, taxes, accounting/financial, etc.
    • We might not want to be very aggressive about splitting either. Only where it makes sense.
    • They may want to have their own wiki space (draft docs, roadmap/planning)
    • While we can do part of this with labels, having subprojects makes it possible to have more granular labels. Ex: taxes have different challenges for Canada (HST/GST per province) than for VAT in Europe. Having a single "taxes" label would be limiting.
    • It's easier to subscribe to issue notifications for a specific sub-project.

Document the account creation, permissions, workflow

"Can a non existing user easily create an account and (issue) report?" (@xavier)

Anyone can create a civicrm.org account, but currently the accounts are still manually moderated (because of spam). It usually takes 24-48h to have an account validated. People can also ping on Mattermost (which is not connected to civicrm.org authentication).

"given the short timeframe to Jira issue creation being closed, is there a 'howto' for how / where to raise issues on gitlab for the uninitiated / non-dev / client minded" (Martin from Circle)

Currently there isn't a guide for reporting issues on JIRA (?), but it would be nice to have one for Gitlab. It's clear that, even for experienced developers, we need a clear guide on how to create a new issue.

"Who can add labels/assign/add milestone?" (@xavier)

Milestones should be added only when the PR is merged. It's impossible to know when issues will be merged, because we release monthly.

What about the 2000 open issues in JIRA that are not confirmed?

"Perhaps some clearer communication as to why those issues are not being migrated and some guidance or a notice posted in JIRA should be provided." (Justin-Agileware)

"I do like the idea of not migrating everything - my wishlist would be for a 'migrate this issue'button" (@eileen)

CiviCRM does occasionally purge issues that have not had activity in 18 months. Batch-closed issues can then be re-opened by people watching them (who will receive an email notification) and still interested on working on the issue.

Therefore we would encourage:

  • More triage of unconfirmed issues before making JIRA read-only, to either close or confirm as many issues as possible.
  • A few weeks before JIRA is set as read-only (including for existing issues), issues will be batch-closed, so that the authors and watchers on those issues receive a notification that their issue has been closed. They can then go in JIRA and request that the issue be re-opened. This might need some tweaking technically, but the short version is that people will receive a reminder to go and update their issue.

To be clear, we do hope to migrate more than the current 39 confirmed issues. The fact that there are only 39 confirmed open issues (out of 2000) shows that more triage needs to be done.

What about Stack Exchange?

(related to points raised by @dtarrant)

Stack Exchange is the front-line of support. Sometimes the answer is "this is a bug, therefore it needs to be tracked in an issue". As with JIRA, we will discourage people from opening support requests in Gitlab.

(duplicate) Won't the separate issue trackers confuse users? what about overlap?

(fixme: needs to be merged with one of the points above)

Ex: a receipt for an event registration shows an incorrect amount. Should this be filed in the 'event', 'contribution', 'accounting' or 'civimail' project? Actually, neither because this is probably just a token issue so should be filed in the 'core' project. ref

We should avoid being over-zealous with the number of issue trackers, and experiment when it makes sense, when it doesn't. Ideally, they should be fairly close to the current list of Mattermost channels. We need to experiment more.

Gitlab also allows moving issues from one tracker to another (although we should only do this during triage, because it would be confusing to code commits with references to a specific issue).

For another way of seeing it: with LeXiM, some core components are being rewritten in extensions. Sometimes a Mosaico bug might be an unrelated core bug, for example. The same applies to the above example.

On being user-friendly, this is indeed a big challenge, no matter what. Currently the dev-team looks like this:

Capture_d_écran_de_2018-01-26_17-13-24

Note that currently there is no "core" project (todo). Ideally, each of those projects should have a clear description. The list should not be too long.

By comparison, JIRA has a lot of very powerful but difficult to use filters. As for Github, we would also have the challenge of whether to open issues in the WordPress/Drupal/Joomla/Backdrop, 'Packages' repositories, as well as extensions. However, Github does not provide a global view of issues and does not allow moving an issue from one project to another.

TODO: Security issues: how to add people to security issues (who aren't part of the security team)

This needs more testing!

Gitlab has a per-issue privacy flag, but we would have to ensure that all issues created have that flag. Otherwise, it might be simpler to make the project fully private.

In any case, this needs more testing.