The current code governance procedures in the Mautic Community have not been updated since the project was founded. The Product Team has been coming across some challenges more recently and as a result we are introducing the following changes.
Proposed tiers for triaging pull requests
We propose a tier-based approach to categorising pull requests (PRs) in the Mautic Community. This would allow the Product Team to establish clear governance approaches to how PRs will be dealt with and what the criteria will be for merging.
These changes will allow the processing of minor fixes and improvements more rapidly, while time-boxing community testing for major pull requests, enabling the Product Team to make decisions on whether to merge new features once those time periods have passed.
Tier 1
Small changes such as typo fixing, bug fixes, translation changes, minor UI improvements or minor enhancements. Most simple bug fixes are probably going to be in Tier 1.
Examples
https://github.com/mautic/mautic/pull/8393 (simple bug fix with very few changes)
https://github.com/mautic/mautic/pull/8116/files (very simple bug fix)
Requirements for merging a Tier 1 PR
-
Thorough testing to ensure that it does what it’s expected to do and does not break anything else
-
Full unit testing coverage
-
Code review from 1 core team member
-
Full testing and approval by at least one community member (could be the person doing the code review, but should not be from the same company/organisation as the person submitting the PR).
As an example: If an employee or contractor from Company A were to submit a PR, the community testing/approval must come from someone outside Company A’s influence (e.g. not an employee, contractor etc of Company A)
Tier 2
Minor features or enhancements which do not significantly change any part of Mautic.
More complex bug fixes are also probably going to be in Tier 2, as well as PRs that are related to external services (e.g. Salesforce/HubSpot) for which accounts need to be created in order to test.
Examples
https://github.com/mautic/mautic/pull/6090 (new feature, fairly simple and doesn’t significantly change any major part of Mautic)
https://github.com/mautic/mautic/pull/7432/ (a lot of new code which extends an existing feature, enhancing reports with a scheduling option)
Requirements for merging a Tier 2 PR
-
Thorough testing to ensure that it does what it’s expected to do and does not break anything else
-
Full unit/functional test coverage
-
Full documentation support if it’s a feature change/addition
-
Code review from 1 core team member
-
Full testing and approval by at least one community member (could be the person doing the code review, but should not be from the same company/organisation as the person submitting the PR as mentioned above)
Tier 3
Major changes touching multiple parts of Mautic, completely changing the way some aspect of the code works, or large amounts of code changed.
Examples
https://github.com/mautic/mautic/pull/6875 (complex code changes across multiple areas, with significant impact)
https://github.com/mautic/mautic/pull/6584 (not too complex but a large visual change in the UI with the potential to cause significant disruption to the end user)
Requirements for merging a Tier 3 PR
-
Thorough testing to ensure that it does what it’s expected to do and does not break anything else
-
Thorough testing across the whole product
-
Full unit/functional test coverage
-
Full documentation support
-
Code review from 1-2 core team members
-
Full testing and approval by at least two community members (could be the people doing the review, but should not be from the same company/organisation as the person submitting the PR as mentioned above)
-
2 week community review period - after which Product Team decides via a vote in the next available team meeting whether to merge (assuming code review and all other requirements are in place to permit merging)
Note: Tier 3 PRs which relate to new features that impact users of Mautic should be linked to in an individual forum thread at forum.mautic.org/c/ideas and discussed on the forums. This gives the non-technical user base an opportunity to be involved in the discussions on new features.
If a thread doesn’t exist prior to the PR being submitted (a feature created without the community suggesting it, for example), it should be created during triage when a Tier 3 & Feature label is added.
The Github URL should be shared in a single line on the forum thread (enables the ‘onebox’ to be created) which will create a reciprocal link on the Github PR.
Proposed tiers for triaging issues
At present there is no documented issue triaging process, and labels are not organised in a structured way. We propose addressing both as part of this process.
To bring issues in line with PRs, we propose adopting the same tiered approach, so that the same label set can be used for issues. We are establishing a triage team, who will be responsible for daily/weekly/monthly and quarterly review processes.
Tier 1 issues
Minor issues which are non-critical in nature.
Examples
https://github.com/mautic/mautic/issues/8974 - an issue with translations
https://github.com/mautic/mautic/issues/8986 - checkbox in the wrong place
Tier 2 issues
Issues which are more complex and/or which may impact a large volume of users.
Examples
https://github.com/mautic/mautic/issues/8621 - impacts all Sparkpost users
https://github.com/mautic/mautic/issues/7062 - appears often but not always when multiple forms are added on a single page, making it tricky to reproduce
Tier 3 issues
Complex issues which impact multiple areas of Mautic or which require extensive debugging to identify/resolve.
Examples
https://github.com/mautic/mautic/issues/9072 - will likely touch many areas and is complex to solve, requiring in-depth technical knowledge of PHPUnit
https://github.com/mautic/mautic/issues/7032 - took a lot of time to confirm the issue and find a proper solution without breaking other things
Labels
We currently have quite a lot of labels which aren’t being used in a consistent way and have little organisation.
We propose cleaning up the labels to make it easier to understand triaging workflows.
It should be possible to group the labels using colours and/or prefixes to make it easier to work with.
Complexity-based labels
-
Tier 1-2-3 [T1, T2, T3] (for PR’s and issues)
Semantic versioning related labels
-
BC Break
-
Deprecation
-
Essential (required to close the milestone)
Type-based labels
-
Bug
-
New feature
-
Enhancement
-
Dependencies (used by Dependabot)
-
Regression
Status-based labels
-
Needs triage
-
Rebase needed
-
WIP
-
Requires automated tests
-
Requires documentation
-
Requires code review
-
Pending feedback
-
Pending code changes
-
Has conflicts
-
Ready to test (PR’s only, and only applied when the PR is passing tests, has no conflicts, has automated tests written and is mergeable)
-
Pending test confirmation (PR’s only, and only applied when the PR is passing tests, has no conflicts, has automated tests written and is mergeable)
-
Ready to commit (PR’s only, and only applied when the PR is passing tests, has no conflicts, has automated tests written, has the required signoff/approvals and is mergeable)
Area affected labels (which part of the product does this affect?)
-
Assets
-
Builders (email and LP)
-
Calendar
-
Campaigns
-
Categories
-
Channels
-
Companies
-
Configuration
-
Contacts
-
Dashboard
-
Dynamic Content
-
Editor
-
Email
-
File Uploader
-
Focus Items
-
Forms
-
Import Export
-
Installation
-
Integrations
-
Landing Pages
-
Notifications
-
Plugin
-
Points/Scoring
-
Queue
-
Reports
-
Roles
-
Segments
-
SMS
-
Social Monitoring
-
Stages
-
Tags
-
Tracking
-
Translations
-
User Interface
-
User Experience
-
Webhooks
-
Widgets
Some points of clarification:
Core team: individuals selected by the Project Lead with technical ability to manage and maintain the core of Mautic - includes Release Leaders, Core Committers, Maintainers (see mautic.org/about/governance ). Currently listed here.
Product team: members of the Mautic Product Team. They may also be part of the Core Team, but not necessarily. Currently listed here .
Triage Team: members of the Mautic Product Team who are responsible for triaging issues and PR’s. They may also be part of the Core Team, but not necessarily. Currently listed here .
Code review and testing: must not be done by the author of the PR.
Closing stale pull requests: If the PR is pending feedback or inactive for over 30 days, the Product Team may decide to close the PR.
Closing stale issues: If the issue is pending feedback or inactive for over 14 days, the Product Team may decide to close the issue.
This is a companion discussion topic for the original entry at https://www.mautic.org/blog/developer/update-mautic-community-code-governance-processes