Pavilion’s open source plugin maintenance involves a number of areas of responsibility. This topic, and associated topics, sets the standard for how a Pavilion plugin maintainer should handle those areas. There are a few benefits to this standardisation:
-
Efficiency. As a maintainer of a popular Discourse plugin there are always many things to work on, and communicate about. Having clearly defined processes reduces the number of decisions you need to make and communications you need to respond to.
-
Equity. It’s easy to get swayed by the latest, or most insistent, plugin user. Balancing the most recent, pressing requests, against previous and or less pushy users, is an important aspect of our approach to the community. Having a procedure to follow is very useful when trying to deal with this on a human level.
-
Interoperability. If all bugs and feature requests go through the same system it’s easy for other members to assist with plugin maintance, particularly in times when the regular maintainer is unavailable. If the plugin maintenance process is ad hoc, there are high barriers to entry for any other member helping out.
Meta Engagement
The starting place for most user engagement for an open source Discourse plugin is meta.discourse.org, primarily in the “plugin topic”. This standardised approach currently has two main aspects, which will be fleshed out further by the pm who takes on this project: https://thepavilion.io/t/devise-and-implement-a-meta-engagement-strategy/1391 (there may be someone lined up to do this soon):
-
A standard plugin template: https://thepavilion.io/t/plugin-topic-template/1434
-
A standard response to plugin users reporting bugs or requesting features, namely directing them to:
-
the bug report and feature request wizards here on thepavilion.io.
-
knowledge base articles (aka documentation) about the plugins here on thepavilion.io.
These two responses should be 99% of all communication in that topic.
-
Bug Reports and Feature Requests
Leading on from “Meta Engagement”, the Bug Report and Feature Request wizards are the primary point of user feedback and engagement about the plugin.
These wizards generate a topic in either #open-source:bug-reports or #open-source:feature-requests tagged with the plugin and (soon) automatically assigned to the plugin maintainer. Those categories act as triage points for plugin communications.
Bug reports are assessed for their relevance and feature requests are assessed for their viability. The heuristics of those assesssments are a subject for another topic: that is an ongoing area of development in our process.
Once a bug report or feature request has been assessed, it is either closed by the plugin maintainer if determined as not relevant or viable, or moved to the #open-source:tasks category if deemed a viable task. When moved to #open-source:tasks, it must be
-
Assigned a due date.
-
If the requester(s) have a budget, given a billable hour and billable rate.
Knowledge Base
Each plugin needs its own knowledge-base here on thepavilion.io. Each plugin maintainer will maintain a sub-category of #open-source for their plugin, using it exclusively for knowledge-driven topics about how the plugin works.
The first post of each topic will be a wiki-style and new-topic creation will be disabled for non-members. In the future, the category may be presented through the medium of the knowledge base plugin or theme component. For now, take the same approach as is taken in #knowledge categories here on thepavilion.io (e.g. #clients:knowledge).
Github
There are a few sub-topics within the Github aspect of plugin maintenance
Issues
In an ideal world, we would turn off Github issues and require everyone to submit bug reports or feature requests via our wizards. However, I think @vsoch made a great point here about why that’s not a good idea:
https://github.com/paviliondev/discourse-question-answer/issues/19#issuecomment-528427694
I find that view persuasive (interested in others’ thoughts as well), so, as a plugin maintainer, you need to also respond to and deal with github issues.
The best way of dealing with github issues is to ask the issue creator to move the discussion to a bug report or feature request on thepavilion.io, similar to our meta.discourse.org engagement strategy.
The reason this is the best way is that it allows us to incorporate work on the issue into our work data system, i.e. the actual hours each member is spending working, where their time is going, and other important management data. Additionally, all the other points about standardisation apply, e.g. it makes it harder for other pavilion members to “Work in”, as they don’t have a single source of truth for what is being worked on.
If the work all happens on a github issue, our system is blind to that work.
Pull Requests
We use Pull Requests for:
-
New feature development, refactorings and large bug-fixes.
-
Non-member pull requests.
A plugin maintainer can make a commit directly to master for small fixes, however the majority of changes should go through PRs, partly for the standardisation reasons already mentioned, and partly due to the need to run tests on the code before it is merged, using Github’s auto-CI features (see Tests and CI below)
We review pull requests using Github’s Review features, i.e. code comments and general comments. There’s no need to move communication on a PR over to thepavilion.io.
But there should always be a task on thepavilion.io for any work the PR is related to, even if it’s a non-member pull request, unless the PR is minor. The reason behind this again is that it makes it possible for other people to work in with what you’re doing.
Readme
The Plugin Readme doc is akin to the plugin meta topic. It’s a primary place for communication about the plugin. We don’t have a readme template yet, but a standard template will be created soon. In the meantime, each plugin maintainer should udpate their plugin readme with the more technical audience of Github (compared with meta) in mind. Importantly, the readme should explain the work management process for the plugin and link to relevant knowledge base articles here on thepavilion.io.
Tests and CI
All plugins should have a full suite of rspecs and acceptance tests that run automatically on https://travis-ci.org/ :
-
Every 24 hours
-
Every time a new PR is merged.
All plugin code should pass against the tests-passed Discourse branch. Plugin maintainers should be notified whenever scheduled tests fail to keep abreast of all issues the plugin may have with the latest Discourse codebase
Translations
All our open source plugins have related entry on transifex.com, which it is the plugin maintainers responsibility to maintain. This includes handling new language and translation requests and maintaining local file integrity between transifex and the locale files in github.
Versioning
All plugin maintainers should follow the policy found in this topic about plugin versioning, namely semantic versioning, which should be reflected in the plugins versioning on github and in the plugin.rb file.
