Adopted March 8, 2021.
Developed and drafted by the VuFind Community Planning Group (alphabetically: Oliver Goldschmidt, Leila Gonzales, Christopher Hallberg, Demian Katz, André Lahmann, Craig Murdoch, Mohan Pradhan, Leander Seige, Hajo Seng); see Acknowledgements below for additional attributions.
The VuFind open source discovery tool is developed as a meritocratic, consensus-based community project. The project's mission is to ensure the long-term technical and financial sustainability of the software, its documentation, and its development processes. Anyone with an interest in the project can join the community, contribute to the project design, and participate in the decision-making process. Particularly experienced members of the community may also have the opportunity to serve on the Project Management Committee, the group responsible for coordinating and managing the project's most critical processes.
VuFind is supported by the Open Library Foundation, an unbiased, independent not-for-profit organization whose mission is to ensure the availability, accessibility and sustainability of open source and open access projects for and by libraries.
This document describes how community participation takes place and how to set about earning merit within the project. It also clarifies the relationship between VuFind and the OLF.
Users are community members who have a need for VuFind. They are the most important members of the community and without them the project would have no purpose. Anyone can be a user; there are no special requirements.
VuFind asks its users to participate in the project and community as much as possible. User contributions enable the project team to ensure that they are satisfying the needs of those users. Common user contributions include (but are not limited to):
- evangelising about the project (e.g. a link on a website and word-of-mouth awareness raising)
- informing developers of strengths and weaknesses from a new user perspective
- encouraging integration between VuFind and other systems (e.g. starting conversations between the VuFind community and complementary projects; reporting new APIs that could add useful features to the software)
- providing moral support (a 'thank you' goes a long way)
- providing financial support (the software is open source, but the project and community need to be sustainable)
Users who continue to engage with the project and its community will often become more and more involved. Such users may find themselves becoming contributors, as described below.
Organizational users are commercial or non-profit entities which rely upon VuFind for some or all of their day-to-day operations. Organizational users might:
- sell VuFind-related services (hosting, support, development)
- offer online tools powered by VuFind (searchable databases, catalogs, etc.)
- use VuFind for internal business processes (e.g. enabling search of an intranet)
As long as they comply with the legal terms of the software's license, organizational users have no specific obligations to the VuFind community. However, it is in their best interest to support the sustainability of the software to ensure that it continues to meet their needs. As such, organizational users are strongly encouraged to contribute back to the community by sharing locally-developed code, by encouraging and/or supporting staff to dedicate time to the project, and by offering financial support when possible. Some forms of support also have specific tangible benefits; see below under "Financial Membership" for more details.
Contributors are community members who contribute in concrete ways to the project. Anyone can become a contributor, and contributions can take many forms. There is no expectation of commitment to the project, no specific skill requirements and no selection process.
In addition to their actions as users, contributors may also find themselves doing one or more of the following:
- supporting new users (existing users are often the best people to support new users)
- reporting bugs
- identifying requirements
- programming (fixing bugs / adding features)
- assisting with project infrastructure
- writing and editing documentation
- developing and running training programs
- offering useful services (hosting, procurement, etc.) to the community
- translating text for internationalization
Contributors engage with the project through the issue tracker, the project's GitHub organization, and the VuFind Tech mailing list, or by writing or editing documentation and other project-related content. They submit changes to the project itself via pull requests, which will be considered for inclusion in the project by existing committers (see next section). The VuFind Tech mailing list is the most appropriate place to ask for help when making that first contribution.
All contributions will be carefully reviewed, and detailed feedback will be provided by the community in a timely fashion. In most cases, some revisions will be suggested or required before a contribution can be merged into the project. As per the project's code of conduct, feedback should always be provided in a constructive fashion, and contributors should view this feedback as an opportunity to learn more about the project and to develop new coding techniques; it is never intended as a personal criticism or attack.
As contributors gain experience and familiarity with the project, their profile within, and commitment to, the community will increase. Contributors who demonstrate a detailed understanding of the project by consistently submitting stable and impactful contributions may be nominated to become committers for the project (see below).
Committers are community members who have shown that they are committed to the continued development of the project through ongoing engagement with the community. Committership allows contributors to more easily carry on with their project related activities by giving them direct access to the project's resources. Most importantly, they have the power not only to submit pull requests, but also to merge them into the project.
This does not mean that committers are free to do what they want. In fact, committers have no more authority over the project than contributors. While committership indicates a valued member of the community who has demonstrated a healthy respect for the project's aims and objectives, their work should still be submitted in the form of pull requests and must still be reviewed by the community before acceptance in an official release. The key difference between a committer and a contributor is that a committer can merge work that has been successfully reviewed, while a contributor must wait for assistance from a committer. For more details on the process, see the section on Reviewing and Merging Pull Requests below.
Anyone can become a committer; there are no special requirements, other than to have shown a willingness and ability to participate in the project as a team player. Typically, a potential committer will need to show that they have an understanding of the project, its objectives and its strategy. They will also have provided valuable contributions to the project over a period of time.
New committers can be nominated by any existing committer. Once they have been nominated, there will be a vote by the project management committee (PMC; see below). Committer voting is one of the few activities that takes place through private PMC communication. This is to allow PMC members to freely express their opinions about a nominee without causing embarrassment. Once the vote has been held, the aggregated voting results are published on the VuFind Tech mailing list. The nominee is entitled to request an explanation of any 'no' votes against them, regardless of the outcome of the vote. This explanation will be provided by the PMC Community Manager (see below) and will be anonymous and constructive in nature.
Nominees may decline their appointment as a committer. However, this is unusual, as the project does not expect any specific time or resource commitment from its community members. The intention behind the role of committer is to allow people to contribute to the project more easily, not to tie them in to the project in any formal way.
It is important to recognise that committership is a privilege, not a right. That privilege must be earned and once earned it can be removed by the PMC (see next section) in extreme circumstances. However, under normal circumstances committership exists for as long as the committer wishes to continue engaging with the project.
A committer who shows an above-average level of contribution to the project, particularly with respect to its strategic direction and long-term health, may be nominated to become a member of the PMC. This role does not change their status as a committer, but it adds some additional responsibilities as described below.
The VuFind Project Management Committee (PMC) consists of those individuals identified on the VuFind website. The PMC has additional responsibilities over and above those of a committer. These responsibilities ensure the smooth running of the project. PMC members are expected to review code contributions, participate in strategic planning, approve changes to the governance model/document, and manage the copyrights within the project outputs. The PMC also votes to fill key roles related to VuFind's membership in the Open Library Foundation, including a Treasurer to manage the project's finances (see below).
Members of the PMC do not have significant authority over other members of the community, although it is the PMC that votes on new committers and responds to code of conduct violations. It also helps to make decisions when community consensus cannot be reached. In addition, the PMC has access to the project's private communication channels. Private communication is used for sensitive issues, such as votes for new committers (see above), discussion of misconduct reports, and legal or financial matters that cannot be discussed in public. It is never used for project management or planning.
PMC membership is for a two year term with no limit on the number of terms a member may serve. Membership of the PMC is by invitation from the existing PMC members. In order to recognize an exceptional committer, the PMC may vote to invite them onto the PMC. In order to fill a vacancy, the PMC can also invite the community to self-nominate, and then vote to select members from the applications received. A PMC member's term begins on the date they are voted in by the other PMC members and ends (or must be renewed) exactly two years after that date. Because active participation and communication are critical to serving on the PMC, members may be removed after 90 days of unexcused inactivity. A member removed due to inactivity may be reinstated later if circumstances change.
In the case of gross misconduct, such as repeated code of conduct violations or serious breach of reviewing/merging protocol, a PMC member or committer can be removed from their role. Such a removal requires a two-thirds majority vote of the PMC. The PMC may also vote on whether to make the ban temporary or permanent, as appropriate to the circumstances.
Ideally, the PMC should be composed of an odd number of members (to prevent deadlock in voting). To ensure diversity of opinion while keeping discussion focused and efficient, the group should contain between five and nine members. When nominating and voting for new PMC members, existing members should give strong priority to representing the project's geographical and organizational diversity. When possible, members should come from different parts of the world and from different types of institutions, in order to ensure that decision-making is not biased toward any particular subset of the community.
The Community Manager is a single individual, voted for by the PMC members. Once someone has been appointed Community Manager, they remain in that role until they choose to retire, or the PMC casts a two-thirds majority vote to remove them.
The Community Manager has no additional authority over other members of the PMC: the role is one of coordinator and facilitator. The Community Manager is also expected to ensure that all governance processes are adhered to, and has the casting vote when the PMC fails to reach consensus. The Community Manager serves as the Primary Manager with regards to the Open Library Foundation (see below).
In addition to the roles described above, which are used internally by the VuFind community, the Open Library Foundation requires all member communities to designate individuals for three OLF-specific roles:
-
Primary Manager - This is the primary point of contact within the VuFind Project for OLF communications and collaboration. This person executes contracts/agreements with the OLF on behalf of the project.
-
Treasurer - this person manages or is deeply familiar with the finances of the project. This person is designated to approve expenditures of the project, can wield a credit card and bank account ownership on behalf of the project, and is available to coordinate with the OLF Treasurer on reporting and annual bookkeeping.
-
Secretary - this person manages the minutes of the project including any resolutions required to document business with the OLF. This person also manages and maintains all contracts brokered and executed through the VuFind SMLLC on behalf of the project, and supports the activities of the Primary Manager and the Treasurer.
For simplicity, VuFind's PMC Community Manager will always serve as the OLF Primary Manager.
The OLF Secretary and Treasurer will be nominated and confirmed by the PMC.
The Treasurer is not required to be a member of the PMC, but the Secretary should be a member of PMC.
The individual serving as the OLF Secretary may also be called upon to serve as an interim VuFind PMC Community Manager if the current Community Manager is temporarily unavailable, or until such time as voting is completed to replace a retiring Community Manager.
While this document details some of the largest and most critical roles and responsibilities within the VuFind project, there are many smaller jobs that support the project's success, ranging from newsletter editing to release management. Because these roles may grow and evolve over time, it is impractical to try to capture all of them in this document; they are instead listed on the Community Roles and Responsibilities web page. The assignment of individuals to these roles is accomplished by vote of the PMC.
All participants in the community are encouraged to provide support for new users within the project management infrastructure. This support is provided as a way of growing the community. Those seeking support should recognise that all support activity within the project is voluntary and is therefore provided as and when time allows. A user requiring guaranteed response times or results should therefore seek to purchase a support contract from an external support provider. However, for those willing to engage with the project on its own terms, and willing to help support other users, the community support channels are ideal.
For more information on the communication channels available for community-based support and external organizations providing commercial support, see the project's Support web page.
Financial membership enables the project to be financially sustainable and, in time, financially independent. Financial membership is available at various levels, with certain benefits applying to each level. Membership levels and benefits are set by the PMC, and current options are summarized on the Membership Levels and Benefits web page. Lack of financial membership does not preclude any member of the community from becoming a member of the PMC, or contributing in any other way to the project. Additionally, membership benefits will never include special privileges relating to project roles or decision-making, as such benefits would be counter to the meritocratic model. Financial support is essential and greatly appreciated, but it is not a substitute for meaningful engagement with the work of the project.
Decisions about the future of the project are made through discussion with all members of the community, from the newest user to the most experienced PMC member. All non-sensitive project management discussion takes place on the VuFind Tech mailing list. Occasionally, sensitive discussion occurs in private, as discussed above under VuFind Project Management Committee.
In order to ensure that the project is not bogged down by endless discussion and continual voting, the project operates a policy of lazy consensus. This allows the majority of decisions to be made without resorting to a formal vote.
Decision making typically involves the following steps:
- Proposal
- Discussion
- Vote (if consensus is not reached through discussion)
- Decision
Any community member can make a proposal for consideration by the community. In order to initiate a discussion about a new idea, they should create a ticket in the issue tracker or submit a pull request. For complex or potentially controversial submissions, sending an email to the VuFind Tech mailing list is also strongly encouraged, to ensure that the submissions receive an appropriate amount of attention. This will prompt a review and, if necessary, a discussion of the idea. The goal of this review and discussion is to gain approval for the contribution. Since most people in the project community have a shared vision, there is often little need for discussion in order to reach consensus.
In general, as long as nobody explicitly opposes a proposal or patch, it is recognised as having the support of the community. This is called lazy consensus - that is, those who have not stated their opinion explicitly have implicitly agreed to the implementation of the proposal.
Lazy consensus is a very important concept within the project. It is this process that allows a large group of people to efficiently reach consensus, as someone with no objections to a proposal need not spend time stating their position, and others need not spend time reading such mails.
For lazy consensus to be effective, it is necessary to allow at least 72 hours before assuming that there are no objections to the proposal. This requirement ensures that everyone is given enough time to read, digest and respond to the proposal. This time period is chosen so as to be as inclusive as possible of all participants, regardless of their location and time commitments.
In cases where lazy consensus cannot be reached, discussion should take place within the comments of the issue ticket or pull request representing the proposal, in order to keep the conversation associated with the submission. If a real-time discussion is desirable, a request can be sent to the VuFind Tech list to have the item added to the agenda for the next scheduled Community Call. If 72 hours pass with no dissenting comments left unresolved in the conversation, and with no pending Community Call discussion scheduled, consensus can be considered to have been reached. Otherwise, voting may be necessary to reach a final decision.
Not all decisions can be made using lazy consensus. Technical conversations that cannot be fully resolved through conversation may need a vote for resolution, and issues such as those affecting the strategic direction or legal standing of the project must gain explicit approval in the form of a vote. Every member of the community is encouraged to express their opinions in all discussion and all votes. However, only a subset of the community have binding votes for the purposes of decision making. The voting mechanism and participants vary depending on the type of vote.
Technical votes are required when consensus cannot be reached around a proposal or submission. The question being voted on should be phrased clearly and unambiguously, such as "Should we merge pull request X?" or "Should we make architectural change / technical decision Y?" Voting should be announced through an email to VuFind Tech. Feedback is welcomed from the entire community, but only committers have binding votes. Votes are made through public comment on the issue or PR under discussion. If, after one week from the start of voting, a simple majority has been reached among eligible voters, the issue is considered resolved. In the case of a tie, a simple majority among PMC members can serve as a tie-breaker. In the case of a further tie, the PMC Community Manager can make the final decision.
As noted above, there are a number of circumstances that may require a vote of the PMC: promoting community members, resolving code of conduct issues, adjusting policies, and making high-level decisions about legal and financial matters. Any member of the PMC may raise such an issue for voting via the group's private communication channel, and group members will have one week to respond. At the end of the voting period, a two-thirds majority must be reached to take the proposed action or make the proposed change. The voting period may be resolved early if all PMC members have participated.
Because PMC voting takes place in private, it is important for project transparency that voting outcomes are shared with the larger community. Votes involving interpersonal conflict resolution -- for example, code of conduct violations -- will not be shared to protect the privacy of the parties involved. All other decisions should be shared to the VuFind Tech mailing list by the PMC Community Manager or Secretary. Additionally, all decisions impacting project direction or policy should be summarized in the next published monthly newsletter.
Much of VuFind's activity is accomplished through GitHub pull requests. This section provides best practices to ensure a smooth-running process resulting in high-quality, stable code.
Contributions typically fall into one of the following categories:
-
Trivial - a change that does not impact the functionality of the code in any way; for example, a correction of a typographical error in a configuration file or comment.
-
Bug Fix - a correction to broken functionality.
-
New Feature/Improvement - added or improved functionality that does not change or break existing behavior. (A new feature or improvement that DOES change/break behavior should be considered Refactoring).
-
Refactoring - significant changes to the code that may impact backward compatibility.
All contributions, even trivial ones, should be submitted as pull requests. Even if human review is not required, this ensures that automated checks are performed, which can help catch and prevent common errors (such as code style problems) prior to merging.
VuFind uses a system of Git branches to manage releases. When creating a pull request, it should be targeted against the appropriate branch.
Trivial and Bug Fix pull requests should usually target the most recent release branch, so these fixes can be incorporated into the next patch release. (An obvious exception to this rule is if the PR fixes a problem that was introduced subsequent to the release).
New Feature pull requests should usually target the dev branch, for inclusion in the next minor release.
Refactoring pull requests should usually target the dev branch, unless a special dev-x.y branch has been set up to track the next major release while a minor release is still under development.
Any committer can merge a trivial contribution, even if it is their own, as long as the Continuous Integration process has passed. All other contributions require a review by one or more other community members.
Any contribution with an approved review by the Community Manager may be merged immediately. For contributions that fall outside of the Community Manager's areas of expertise, the Community Manager may delegate the review to another individual with appropriate experience, and the contribution can be merged after that individual's approval. It is the responsibility of the Community Manager and his/her delegees not to approve pull requests that may require more review and discussion prior to merging.
Any contributions with approvals from one or more committers operate on the principle of "lazy consensus" and may be merged if there are no objections or suggested changes within 72 hours of the first approval. This 72 hour waiting period may be overridden by a majority vote of the PMC if there is an urgent need to merge a contribution more quickly. For contributions that cannot reach "lazy consensus," the voting process described above should be followed.
Committers and members of the PMC are strongly encouraged to follow the project's GitHub organization so that they will receive notifications of new pull requests and can contribute reviews as their time and expertise permit. Contributors are also encouraged to send a message about their contribution to the VuFind Tech mailing list if they do not receive a review in a timely fashion.
This document is based in large part on the OSS Watch "Template for a Meritocratic Governance Document," which was written by Ross Gardler and Gabriel Hanganu and licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.