Closed Andersson007 closed 1 month ago
cc @cybette @Spredzy @GregSutcliffe @oraNod @samccann @anweshadas @leogallego please share your thoughts:) If no thoughts, feel free to ignore:)
@Andersson007 we have the start of recommendations in the Project Onboarding toolkit (including a recommended docs structure), and the github project template that matches it.
On the things we'll have difficulty with - we can recommend projects follow the github project template and docs structure, but we don't have the authority to ensure it happens so to speak. We lack an overarching governance model that could help enforce these items.
@samccann thanks for the links i'll take a look
On the things we'll have difficulty with - we can recommend projects follow the github project template and docs structure, but we don't have the authority to ensure it happens so to speak. We lack an overarching governance model that could help enforce these items.
Even if there's the gov model working, practically it'd be hard to force folks do things anyway imo. Speaking more radically, maybe we even shouldn't force them. Like that semver vs calver vs number-of-digits-in-calver thing - as long as a used versioning convention is documented and it's easy to find, is it really an issue preventing people from contributing? But it's another topic..
There are thing we can do ourselves now.
Let's take one example: one of the spotted issues is the lack of communication guides in the projects.
To solve this, we could come up with a template that will contain some cross-project channels (like Bullhorn and social Matrix channel, etc.) and leave space for project-specific ones once or fill up them two if we know).
Then we could add this as project communications guides. Once we have a README template, this should contain the Communication
section containing a link to a project-specific communication guide. In this case every project will have a similarly structured part of README about communication guide and similarly structured communication guide on its docsite. I'm sure nobody will be against if we submit the PRs themselves. A real example is c.postgres communication guide we now use in several collections with minimal modifications (they don't have docsites, so we put it just in their READMEs).
Another example: it looks like the projects mostly follow SemVer but there's no explicit info about it. So there could be a section in the README template called Versioning convention
.
This are just examples what we can do ourselves now.
So my proposal for now is:
How about the plan?
@Andersson007 Just reading through this and my thoughts are similar to what you and @samccann have already said. In here there are things we can do something about and other things that are purely up the respective project.
It would probably help to break items into categories of what we can control and take action there, meaning we can submit PRs for things like the Communication
sections as you said. I'm willing to help with that side of things.
For things we can't control I think we could at least outline recommendations and notify teams, asking them to adopt or apply where possible.
Problem statement
The Ansible Ecosystem is made of over 20 projects our engineering organization is the biggest contributor to. Despite all those projects being part of the same ecosystem their contribution practices and experience vary widely.
Objective
To provide a well crafted, comprehensive and consistent Contributor Experience across the majority of the projects to enable contributors to easily be able to land and expand in our ecosystem.
I walked through all the projects. Below is what I found out.
Spotted patterns and thoughts
Possible solutions to some common issues
I think we should try to come up with a more or less global solution, not trying to tackle small bits incrementally right after they come to mind. I think we could use the project_template repo to polish stuff like, say, the README template or docsite file/section structure trying to engage the broader community in the process. Also we should do (or at least initiate in PR form) most of the work themselves -and resp first come up with solutions that can be done by us- as it’s practically hard to make maintainers do anything even if they agree.
Any inputs would be much appreciated. I could start coming up with implementations ASAP.
Sub-tasks:
Related discussions: