RFC: Updated Backstage Governance #15317
Comments
|
So happy to see an active desire for getting help from the community to move the project forward. ❤️ For the past few months, I have been asking similar questions to myself - what avenues do I have in front of me to help out. When I was at Spotify not so long ago, organizing backstage community sessions, doing discord support in weekly livestreams, occasionally joining "boss syncs" to look for opportunities to help, it was just a "Google Meet" away. Now, all of those ways have suddenly disappeared. Perhaps a more direct ownership to some parts of the project as described above and some incentives can guide people (like me) who are looking to invest their energy but aren't exactly sure in what ways. |
|
Another thought around maintainers being active/inactive in open source projects like Backstage is that if their employer is not willing to sponsor their open source contributions, they find it very hard to keep dedicating their time. Rarely anyone uses Backstage for their personal project :P - so as long as Backstage is even remotely related to anyone's full time work, it's easier for them to stay involved. Maybe there is an opportunity to incentivize employers to sponsor such maintainers by letting them spend a percentage of their time on the project. This could be as simple as a page like |
|
This is great, @Rugvip. I'm wondering if introducing the "Author" role makes sense at this point to highlight that not necessarily the "Author" has to "maintain" and that way encourage the "Maintainer" status. |
|
This is an excellent step towards a more accessible path to maintainership. It would be helpful to flash out and define what role SIGs are expected to play in the governance model. The current section shows that we currently need some clarity in this area.
We can also lean into SIGs without tying code ownership to SIG ownership. Doing so would support the idea that we value all contributions, not only the ones that can be expressed as code.
This sentence sounds like SIGs are a channel for providing support. The Adoption SIG is explicitly not a support channel, as mentioned in the FAQ. We could make Catalog SIG more action-centric to help push some known issues. Do you think we should break this out into a separate discussion or continue here? In any case, excellent work on this RFC. I'm delighted to see this coming together. |
|
@Rugvip I'm happy to see the team working on improvements to Governance! We have our Monthly CNCF Governance WG meeting this Thursday at 10:00am PST, and it would be great to have a couple of folks from the Backstage team attend to talk about this RFC! Details about joining the meeting: https://docs.google.com/document/d/1P9tQgCM6OwDHd1F8UnWuauL4KDVTMTp49_n64_w8nrs/edit?pli=1#heading=h.fdbtb24sf1jw cc: @jberkus |
|
@OrkoHunter yep, a list of contributors and their orgs would be part of the implementation of this for sure! 👍 We'd likely list reviewers, maintainers, and project maintainers. @waldirmontoya25 I think an author would likely be a contributor or an org member, unless reviewer or maintainer for a particular section of the docs. I talk a bit more about that under "Lack of non-code contributor roles" as well. Does that sound like an alright middle ground or do you think me might need something extra in this space? @taras to elaborate more on why I'm thinking it's best to keep SIGs separate: The main thing is I'd say SIG are by definition open, meaning they are supposed to be running some form of public forum where members of the community can join. I feel that's a big ask for a lot of project areas, and would rather have that as an optional extra for more well-established areas. Basically I worry the overhead of SIGs is a bit too high compared to their benefit. In addition, SIGs aren't really great for ownership by themselves and require additional structure similar to project areas on top. So in the end I feel SIGs fill an important role as a forum for discussing and aligning work throughout the community together with maintainers, but are an additional extra separate from project areas. SIGs are definitely not support channels. Does that address your concern? @geekygirldawn thank you for having a look! Sorry we weren't able to join. Related to the comment in the doc I'd be happy to have a closer look at any other templates you recommend. I've had a close look at the contributor ladder one, as well as the subprojects template, which I discussed a bit in the alternatives section. I'm thinking we'll make a separate update to address the organization wording in the governance related to the Envoy roots. I'll also let you know as soon as we make a more concrete governance update proposal for this in the form of a PR. |
|
Notes: First, consider dividing up the contributor ladder and the other governance matters into two separate documents.
Earlier conversations indicated that you wanted to get away from the model of having subprojects. This section, though, suggests that you plan to embrace it, via a SIG system.
The other thing that helps is having clear, written criteria for exactly what a contributor needs to do to qualify for consideration as a maintainers. This helps for several reasons: it's easier to work towards a goal if you know how close you are, it's way easier to get permission from your boss if they know what you're committing to, and it's easier for existing maintainers to evaluate new candidates if they have some clear criteria to work with. The paragraphs in this RFC are a good start. Consider borrowing from TAG-CS's contributor ladder which is an example of making things as quantitative as possible.
Yeah, if it makes sense, the way to simplify that model is to simply make all subproject maintainers part of the general project maintainer group. As long as the pool of maintainers is relatively small, that can work fine. |
Do you expect working areas to be closed? I've been in communities in the past where all of the decisions were made by small groups out of sight of the community. They would produce RFCs but those RFCs already eliminated many options and narrowed scope of feedback. It made the groups cliquy. The communities ultimately failed because formed echo-chambers and missed changes in the industry.
On the flip side, it can add more meetings and require more effort to broadcast information.
I'm not sure. My primary concern is to ensure clarify on the relationship of SIGs and working areas. I'm not sure what is the best medium to do that - Backstage Contributor Sessions? Aside, CNCF Technical Advisory Groups has some interesting ideas. One thing that I like is "TAGs may choose to spawn focused and time-limited working groups to achieve some of their responsibilities (for example, to produce a specific educational white paper, or portfolio gap analysis report)." The ability to form temporary special purpose groups seems like a very nice feature of their Governance model. |
WGs for TAGs are analogous to the Subprojects of SIGs in Kubernetes. Kubernetes also has a concept of WGs which is different. I think all of this may be fairly elaborate for Backstage though; consider that the project has about 30 people, total, who contribute 10 or more PRs a year. |
I expect them all to be reasonably open, especially to feedback and ideas, keep all contributions visible in PRs. I wouldn't expect all areas to do all their work out in the open and be running SIGs, it's a lot of overhead. One of the purposes of this structure is to allow for more lightweight ownership in order to make it possible for more members of the community to participate, even if they don't have buy-in to spend all of their working time towards Backstage OSS. I think this is an area were we can evolve the setup as well. If we end up seeing that some areas are primarily operating behind closed doors, keeping the rest of the community in the dark, and that leads to problems, we can adjust our requirements on the project areas.
In my opinion our documentation and release process needs to be good enough for this not to be the case.
I think continued discussion here is the best at this point to be honest. The relationship as it is proposed in this RFC is that project areas may choose to run SIGs, and there may be SIGs run that cover existing project areas. Exactly what is discussed and done in SIGs isn't enforced in any way at this point, SIGs are more akin to self organizing interest groups. |
|
Heads up that we'll close this for comments on Feb 13th, and then move on towards an implementation. If you have any more comments, now's the time! 😁 |
|
@Rugvip any update on implementation? Is there anything we can do to help get this moving? |
|
@serenamarie125, @jhaals and I are moving this along, hopefully more to share soon 😁 |
|
Implementation proposal is now ready in #16740 |
|
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions. |
|
Closing as this is now implemented 👏 |
Background
Backstage’s GOVERNANCE.md is largely inspired by the Envoy project, which has a large, broad maintainer team with individuals specialized in different areas, while we are a much smaller team and less specialized. We have been wanting to grow the maintainer team for some time, and have had multiple requests from contributors and contributing organizations that they want to become maintainers, but none of those discussions have ever really gotten off the ground.
🔖 Need
Becoming a maintainer is too hard
Our typical response when someone wants to become a maintainer is that they should make sure they are involved in the community, help out with support, review pull requests, and make significant contributions to core systems. After several months of presumably full time work, the maintainers are then supposed to confer and decide whether the contributor should become a maintainer or not. So far this process has never gotten off the ground, which isn’t too surprising.
We’ve had interested potential maintainers, but going from spending a bit of time on the side to dedicating most if not all of your working time for several months is a very tall order. The project has also grown a lot, and expecting someone to journey from an understanding of a few parts of the project to a complete holistic view before receiving any kind of ownership is unreasonable.
There is a strong need for an introduction of more steps in-between a new contributor and being a maintainer. An important part of this is to be able to slim down the scope and responsibilities that contributors take on, which can be done across a couple of different dimensions.
One might limit to fewer types of contributions, selecting a subset out of all the ways to contribute, for example through code, pull request reviews, issue refinement, UX design, community discussion and support, architecture, promotion and outreach, product management, documentation, and so on. All of these types of contributions are valuable and we want to make sure we encourage all of them, without making it a requirement to fill all those roles at once. The other dimension is what part of the project you contribute to, be it the core framework, specific plugins or integrations, the microsite, etc. Likewise, we want to make it possible to have a maintainer role with a more narrow scope and ownership of a smaller set of concerns.
Ownership model
Since the beginning of the Backstage Open Source project we’ve had squads at Spotify that own particular parts of the project. The most notable example of this is TechDocs that is owned by the Pulp Fiction squad at Spotify, who later on also have taken on the Search and Homepage plugins. Some other examples with owners from Spotify are the Kubernetes and Cost Insights plugins, and there are a couple more. Apart from these couple of plugins, the maintainers have been the owners of the rest of the project.
This ownership model has a couple of issues. Most notably at this point, the maintainers are overloaded and do not have enough bandwidth to review contributions to all parts of the project that they own, especially not while also trying to move the project forward. There have been some attempts to bring in reviewers and owners for some plugins, but it hasn’t worked particularly well. What I feel that what has been lacking is a more direct sense of ownership, as well as any tangible benefits. Being the owner of a plugin doesn’t help you become a maintainer, for example. There also aren’t enough processes in place to make isolated plugin ownership simple.
Another issue is that this current ownership model isn’t inclusive of the community, regardless of whether it’s new plugins built by squads at Spotify, or existing plugins that Spotify wants to support. This is both from the point of view that members of the community don’t have an opportunity to use the same kind of ownership model for their own plugins, but also that we don’t open up for community members to become maintainers of existing plugins. One of the things I feel is needed for this project to scale well is to be able to create sub-communities around different areas, and that’s not going to happen if there are fences keeping people out.
🎉 Proposal
This proposal includes a couple of updates, all intended to work well together and address the needs outlined above. They don’t dive into implementation details, we would handle that in eventual future pull requests that implement these proposals.
Contributor ladder
I propose that we introduce more steps in between first-time contributor and maintainer, in the form of a contributor ladder. This would be heavily inspired by the ladder in the CNCF Project Template, and we would add a similar document to the main Backstage repository. The purpose of the ladder is to introduce smaller steps, but also to make the requirements and responsibilities of each step as clear as possible.
By introducing the contributor ladder we make it possible to highlight many more members of the community, regardless of their particular type of contribution and amount of time that they’re able to invest in the project. These members also get the opportunity to get more involved in the project for each step up the ladder, with increased responsibilities and ownership.
We likely don’t copy the contributor ladder from the CNCF project template verbatim, but adapt it to fit our project. One particular change that I propose is to bump the project-wide responsibility up one step so that Maintainers own a specific project area. This is to allow for complete ownership of individual project areas, rather than just reviews. We then add Project Maintainers as another step, who are responsible for coordinating work across the entire project.
To give a quick and incomplete concrete example, the ladder might look as follows:
Contributor
This is a member of the community, there are no responsibilities other than to follow the Code of Conduct and Contributor Guidelines. Everyone is inherently a contributor if they are involved in the project.
Org Member
An org member is a frequent contributor that has become a member of the Backstage GitHub organization. In addition to the responsibilities of contributors, an org member is also expected to be reasonably active in the community through continuous contributions of any type. To become an org member a contributor must have a number of contributions of varying types, and also have been a contributor for a certain amount of time.
Reviewer
A reviewer is responsible for reviewing contributions to their specific areas of responsibility, and are expected to review a certain number of pull requests per year. To become a reviewer an org member needs to have reviewed or helped review a certain number of pull requests, demonstrated in-depth knowledge in their specific area, and be backed by the existing project area maintainers or project maintainers if it is a new area. Reviewers are also responsible for helping contributors become org members and reviewers.
Maintainer
Maintainers are owners of a particular project area, with project areas being a new concept that is introduced further down. They are expected to review and merge pull requests towards their area, and also drive development and manage tech health. A maintainer also needs to commit a certain number of hours per month towards the project, and exercise judgment for the good of the project, independent of their employer. Maintainers should also mentor new reviewers and participate in and lead community meetings related to their area. To become a maintainer one needs to have experience as a reviewer for a number of months, demonstrate a deep knowledge of their own area and how it fits into the larger Backstage project, and be backed by the existing project area maintainers or project maintainers if it is a new area.
Project Maintainer
Project maintainers are responsible for the Backstage project as a whole. They help review and merge project-level pull requests as well as coordinate work affecting multiple project areas. A project maintainer needs to commit the majority of their time towards the project, and exercise judgment for the good of the project, independent of their employer. Project maintainers should also mentor and seek out new maintainers, lead community meetings, and communicate with the CNCF on behalf of the project. To become a project maintainer one needs to have been the maintainer of a number of different project areas, demonstrate a deep knowledge of large parts of the Backstage project, and be backed by the existing project maintainers.
New ownership model
We divide the project up into several project areas, each covering particular parts of the project. The main driver for each area is ownership of code in the main Backstage repository, as well as other repositories in the Backstage GitHub organization. Each area has a set of maintainers, reviewers, and repository content that they own. There may be no overlap in ownership between areas, which is defined as multiple owners for a single line in the GitHub code owners file. Each area is represented by a team in the Backstage GitHub organization, and may be further divided into reviewer and maintainer teams. Apart from certain project-wide concerns, such as the release process, each area is self-governing and chooses their own ways of working. Project areas may also have special interest groups (SIGs) related to their area, but this is not required.
This RFC does not propose any particular project areas, leaving that for future discussions.
Each project area must have at least one maintainer or reviewer. A project area that only has reviewers is considered an incubating area where the reviewers are there to help drive work forward in the area but they might not yet feel ready to take on ownership. The goal should generally be that these reviewer(s) eventually become maintainers of the project area. This is to allow for a more smooth onboarding and transition of ownership, where members of the community might for example be new to open source maintainership.
The size of the project areas can vary and the intention is for them to evolve over time. An area might for example agree to take on new responsibilities, or large areas might be split into smaller ones. One type of area that may exist are “catch-all” areas where they own everything in a particular category that isn’t owned by someone else. One example might be an area that owns all source control integrations, except where another area owns the Azure integration.
Backstage Enhancement Proposals
This related proposal is handled in a separate RFC, as we want to keep the discussions separate.
〽️ Alternatives
Split repositories
A frequent discussion topic among the maintainers is whether we should be splitting the project up into more repositories rather than to keep scaling the work in the main repository. We still don’t feel that we’re quite at the point where we feel comfortable pushing this forward, but would rather find ways to split ownership in the main repository for now. Long-term I think we will want to do both, but there are both technical and organizational hurdles that we’d need to overcome. Either way the core parts of the project that we would keep in the main repository are large enough by themselves that it makes sense to break things down into smaller areas.
SIGs
One alternative to the project areas is to lean more heavily into SIGs and make them the source of ownership instead. In the proposed model SIGs become an optional part of each project area, but there may also be SIGs for more horizontal concerns or multiple areas. One of the primary reasons for not making SIGs the starting point of project ownership is that they’re more geared towards getting people together to discuss and spread knowledge, rather than executing and moving development of the project forward.
Subproject Template
There’s a fairly new subproject template from the CNCF that
#tag-contributor-strategyjust released documentation for as I was done writing this proposal. There is a lot of overlap and I think we’ll be able to lean on many parts of the template in an eventual implementation of these governance updates. The template does however propose a structure of subprojects along with a steering committee. I feel that this structure might be something that we should consider further out in the future, but that it would be very tricky to move straight to that model. It’s mentioned in the documentation for the template that one of the requirements is that “the different subprojects share few or no maintainers”, and it will take us some time to reach that state.CNCF Maintainer Contacts
The proposed contributor ladder gives the project maintainers the responsibility to “communicate with the CNCF on behalf of the project”. This effectively means that from the CNCF’s point of view, the project maintainers are the maintainers of the project. We don’t necessarily need to structure it this way though, and could instead for example lift up all or some of the project area maintainers to interact directly with the CNCF as well. I think starting off with the project maintainers likely makes sense, but it’s perhaps something we can tweak if we see a need further down the line.
❌ Risks
Maintainer workload
Rolling these changes out would further increase the workload on the maintainers and de-prioritize other ongoing work. In the end I feel that this is a necessary step. Of course one of the goals of these proposed changes is to scale the maintenance of the project.
Inactive Members
Something that inevitably will happen is that org members, reviewers and maintainers will become inactive. Of course it’s best to voluntarily step down in this situation, but there is also a process for handling inactive members in the CNCF project template that we would likely adopt.
Conflicts
With ownership being moved around and with a ladder to move up it is likely that there will be conflicts of different kinds. These are of course hard to predict but will need to be handled with care. It is important that the maintainers and project maintainers are equipped to deal with these situations and also have resources to lean on from the CNCF and other organizations.
Lack of non-code contributor roles
The proposed contributor ladder requires some form of ownership of code from the reviewer role and up. This would seem contrary to the highlighted need of more ways to encourage non-code contributions such as community support and outreach. The way I see this is that it’s best if there always is some form of ownership by all senior members of the community, but it may be in the form of guides, documentation, internal documents, and so on. For example, community members geared towards community management and outreach might own the backstage/community repository, while ones working towards developing strategies for adopting Backstage might own that section of the documentation.
The text was updated successfully, but these errors were encountered: