As I’m sure everyone in the Ansible community is aware, there are loads of great and really useful projects out there to help you automate. Since we launched the ecosystem page on the docsite we’ve had some discussions about what projects get included there.
The question exists, what are the “table stakes” for projects to be included in the ecosystem page? Let’s have that conversation.
It seems like there are some minimum requirements for projects:
Be available here on the forum in case there’s an issue and the community needs to get in touch.
If the project is a single-person, there needs to be a clear succession plan. This avoids the scenario when a single maintainer disappears and leaves no access to the project.
User documentation must be available.
This is just a start and there are bound to be more criteria. @samccann has mentioned “usefulness”, which seems fair enough but maybe needs to be a bit more specific so it’s not so subjective.
I think the spirit of “usefulness” means not only relevance to Ansible automation but that it has broad enough functionality that it benefits the general community in some way. However that feels tricky to define because it risks excluding projects that are genuinely useful but have fairly narrow use cases.
So tell us what you think. What do you see as the “table stakes” that projects need to meet in order to be included on the ecosystem page?
As an outcome I would like to codify these criteria somewhere, probably in the docsite README, and then use them as the basis for expanding the ecosystem beyond what we have today.
Thanks for the write up! I’ll respond overall later, but I just had a couple drive by things:
I don’t think we should require a share-alike licenses. There are ecosystem stuff under MIT or Apache-2.0 licenses and such which are definitely worth including
I’d prefer not to require certain specific code hosting platforms. If the spirit of this is that the project is set up in a way to enable community contributions, I think we should phrase it like that. Github and Gitlab.com are both closed source platforms[1]; I don’t think we should tie the ecosystem page to it.
There is Gitlab CE, but the hosted version contains non-free code. ↩︎
I agree that using a ShareAlike / CopyLeft license shouldn’t be a requirement but I think having a OSI approved one is a good idea (personally I think that using a FSF approved CopyLeft one is an even better idea…), as suggested above:
The Apache and other permissive licenses such as BSD /MIT / X11 ones are OSI approved.
This is probably fine, though it feels a little arbitrary. Ansible is open source, but that doesn’t mean every tool in its ecosystem needs to be (e.g. I’m sure some people in the community use Steampunk Spotter despite its closed nature.)
Git is not the only RCS (it’s not even the only open-source distributed RCS) and its use has no bearing on whether a project is a useful part of the Ansible ecosystem.
Use of Github “or equivalent platform” seems to be a proxy for some other set of actual requirements (e.g. having a bug tracker with open registration) which would be more useful spelled out individually.
This should not be a requirement. It’s both difficult to police and again seems like a stand-in for the real requirement, which is having an available contact method.
I don’t see this having any practical impact. If a project currently is developed by a single person then 99% of the time it will die if that person disappears, regardless of whether that person has given access to other people (and in the 1% whoever is actually maintaining it is doing so in a fork because they weren’t the other person with access to the original repo, who has also disappeared. )
I think the page should be split up into multiple pages that have a narrower scope. For example, projects like ansible-compat, antsibull-docs-parser and antsibull-docs-ts (only the first one of these is on the list right now) are only of interest to a very small group of ansible tooling developers.
Other tools like antsibull-docs or antsibull-changelog are mostly of interest to collection maintainers, but (usually) not to regular users.
ansible-lint is both of interest for collection maintainers, collection contributors, role authors, and regular users.
etc.
So having pages for specific user groups (and tools showing up in one or more of these pages) is probably a good idea.
While I prefer sticking to OSI approved licenses myself, it’s clear that it would be strange to not mention non open source things like Steampunk Spotter. I think it would be a good idea though to have such projects listed separately (clearly marked as not open source).
Some first ideas:
Having an accessible bugtracker that can be used free of (extra) charge (extra to the price you have to pay to use it, i.e. 0 for open source products);
Open documentation that can be read without registration or payments (so you can take a look at what the product can do);
Free evaluation possible (without having to provide more personal data than strictly necessary by GDPR, for example);
I agree here. For open source projects this is not really necessary anyway, as it’s easy to fork them if necessary. On the other hand, for non open source projects, this is more important. But I think this is already covered if non open source projects are explicitly marked (and listed separately from the open source ones).
Let’s start with defining more strategic level. My spontaneous brainstorming would be:
Introduce formal requirements (thanks everyone for great suggestions)
Establish a limit for the number of projects on the ecosystem page if we don’t want the whole internet reside there. Part of the slots will belong to RH projects (as main and only sponsor) like Ansible Core, AWX and the collection link, to name a few.
Conduct yearly community votes for the community projects part (can be faked though). Only projects that satisfy the requirements can nominate. SC members can conduct the reviews similarly as we do for collection inclusion requests.
Hey, thanks for the responses so far. It’s great to see these opinions. I’d like to clarify a few things about the intent behind the initial criteria I outlined.
OSI approved license
Yes, it’s true that not every project in the wider ecosystem is open source. However the ecosystem page on the docsite is hosted on Red Hat infra and includes a “sponsored by Red Hat” entry on the footer. As a proud Red Hatter I would feel very uncomfortable with the idea of including closed source projects on the ecosystem page, even if they are awesome and useful. Including closed source projects simply goes against some basic fundamentals in my opinion.
Outside my personal views, it might not be feasible from a legal or other perspective to include closed source projects or projects with non OSI approved licenses on a page that Red Hat sponsors. Perhaps I’ve been naive in assuming that everyone in the community would automatically approve of the OSI approved license criteria that I set out. Other viewpoints are welcome but let’s keep in mind the fact that the ecosystem page is a Red Hat website. Open source is in our (Red Hat’s) DNA as I’ve heard it said recently. I’ll ask some folks in Red Hat who can give us clear guidance on this one and will get back to everyone on this thread.
Git RCS and hosting platform
I really like some of the counterpoints and suggestions coming up with this one. I put this one down mostly so that we have some standards that make things cohesive for maintainers and contributors. One of the initiatives of the community team recently has been to assess projects with a view towards identifying differences and smoothing things out so maintainers/contributors don’t have to do too many mental gymnastics when switching between projects. There’s already enough variation between projects on GitHub.
However I take the point from @gotmax23 that there are other open source alternatives out there and we shouldn’t tie the ecosystem page to closed source platforms. As @flowerysong mentioned we can work towards spelling out these requirements individually. Hopefully the initial intent is a bit more clear now.
Be available on the forum
The intent here is beyond having a contact method. If the project is on the ecosystem page the maintainers should be active participants in the community. Our forum should be the de-facto place for community interactions.
Clear succession plan
I’ll invoke @gwmngilfen on this one but we spoke about this as a lesson learned. There have been instances in the past with other communities where single maintainers abandoned projects, effectively locking the rest of the community out of a project that they were actively using. It’s true that you can always fork but it still takes time to ramp up on that fork. The intent here is to avoid any single point of failure.
Documentation
I didn’t see any comments on this criteria but I would like to develop it a bit more and outline some specific standards or levels that project docs must meet. For me docs are an indicator of project maturity and commitment to user success. I think those two things are important considerations. Maybe we just need to spell them out clearly.
Thanks for the comment @Andersson007 For #1 that is what I would like to try and achieve with this discussion. After we have the formal requirements we can address the process stuff, #2 and #3. I would prefer to tackle those items in separate discussions to keep the focus on the table stakes.
@felixfontein These are good thoughts for sure. We’ve been talking about adding categories and improving the organization for the ecosystem page recently. Right now it’s just alphabetical order. I’d like to keep this discussion thread scoped to the table stakes as much as possible. Would it help if I created an issue in the docsite repo to figure out a new design / category layout? We could move this convo there.
Seems like we might have multiple types of projects:
RH-managed projects (what the current page has)
community-managed projects (by active community members here and in matrix - I’m thinking things like the antsibull-docs etc…)
Other opensource ansible-related projects
Closed-source projects
Today the ecosystem page is the RH-managed projects. And awesome ansible repo lists ‘other open source ansible-related projects’ and ‘closed source projects’.
My inclination is to keep awesome ansible as the place for other projects (open and closed source) and maintain it better. We can then link to it from ‘some page’ as other resources. The ecosystem page (and any subpages by category) should be active community projects imo. That means yes, they need to be here on the forum as part of those basic table stakes. And they need to be open source.
I also agree. This is a list of external projects on a page. Maintainers of the page must periodically check that the projects still meet all the criteria, one of which is being “active”. If it doesn’t meet that criterion, remove it from the list.
I think it’s too much for maintainers of the list to have to dig into a succession plan to assess its viability, especially since as @flowerysong said, 99% of the time, the project is going to die on abandonment anyway, that’s just the nature of OSS.
To expand on that on from my personal experience (skip this if you want): the largest project I maintain is hvac. It has nearly 1,200 stars, it’s linked to from HashiCorp’s docs almost as though it’s official or supported by them (it is not), it has a lot of users. In theory, we have 3 active maintainers including myself; in practice I’ve been the only active one for a while now (no shade intended!), and despite a concerted effort to get more contributors who I hope could eventually become active maintainers, the project sees limited contribution interest.
All this to say: I could write up a succession plan of some kind, but it will mean nothing practically, and will probably boil down to, “I’m gonna post an issue asking for replacements and see who steps up”, which there’s nothing wrong with, but is that a helpful criteria for linking to a project on an ecosystem page?
Is anyone maintaining this? There haven’t been updates in 8 months, the first link in the list I clicked on (terraform inventory) is an archived repository, and there are 4 open PRs, 3 of them have no response.
(I was going to submit a project there… )
We did bring it up briefly here, but never really resolved it. Basically it needs a group to determine what can be added to the awesome ansible list, and merge the PRs (and go in and remove stale projects that are no longer maintained etc).
I think it was moved to the ansible-community org with the understanding that we, the community, would help maintain it going forward… but we haven’t.
I’m super late to this thread, but I’m loving the discussions that have taken place.
FWIW, I’m also +1 to the list as written at the time of my writing this:
* OSI approved license
* Use the git distributed revision control system.
* Hosted on github.com or equivalent platform.
* Be available here on the forum in case there’s an issue and the community needs to get in touch.
* If the project is a single-person, there needs to be a clear succession plan. This avoids the scenario when a single maintainer disappears and leaves no access to the project.
* User documentation must be available.
In addition to that, I like the concept of having a good categorization structure to allow for “end user” vs “contributor” type ecosystem offerings. We could get more granular than that if desired. I also saw it mentioned that there could/should be a differentiation of Red Hat sponsored vs not Red Hat sponsored and if there’s a desire to call that out explicitly from the broader community then I don’t have any real reservations, but I would like to ensure we’re highlighting the Ansible Community at large, the projects built on/around Ansible technologies, and give them an equal opportunity for being listed/highlighted on the Ansible Community Ecosystem space regardless of if they have a corporate sponsorship or not.
We shouldn’t imo use the same set of requirements for RH and non RH projects.
To achieve what you mentioned, RH requirements should also cover things like great contributing guidelines presence, common docsite and README layout, versioning specifications defined, etc., i.e. RH projects should adhere to higher and predictable standards.
This stuff should be best and similar in RH projects but I don’t think we should interfere in contributor experience stuff in third-party projects.
Don’t refer to any project lists you can’t/not going to maintain from the ecosystem page. Put a general note instead that it does not list all the ansible-related projects.
While defining the requirements we should keep in mind who and how will decide on any subjective requirements and also the mechanisms of selection and control. If something is on the official ecosystem page it must follow some requirements. If there are requirements they must be controlled anyhow.
The periodic project revision will be needed anyway, so we should keep it in mind. Maybe there should be some limits on a number of project on the ecosystem page(s) to make the revision feasible and let resources like awesome ansible define the rest.
Several pages with narrower scopes, i.e. for specific user groups, sounds good.
RH projects will have more requirements to get included in order to provide greater cross-project contributor experience and to adhere to greater standards in general.
See below my requirement list, thoughts on initially suggested requirements + details on the above points.
Publicly available free of charge and registration issue tracker
Publicly available free of charge and registration user documentation
Can be ignored now: RH projects will have more requirements related to better cross-project contributor experience
Why this list, see below.
Thoughts on initially suggested requirements and later comments
+1 to the requirement to support open source:)
What practical goals do we pursue with requiring this?
If it’s about contributor experience, there should imo also be at least changelog presence, development guidelines presence, etc.
If this is about open source stuff, aren’t they already implied by the OSI approved license requirement?
Anyway having free-of-charge-and-evaluation issue tracker and user docs as @felixfontein suggested sounds good to me.
We shouldn’t use the same set of requirements for RH and non RH projects.
To achieve what you mentioned, RH requirements should also cover things like great contributing guidelines presence, common docsite and README layout, versioning specifications defined, etc.
This stuff should be best in RH projects but I don’t think we should interfere in such stuff in third-party projects.
The requirements we’ll define here will for any project should be imo a sub-set of requirements for RH projects.
It’d be hard to enforce but +1 to this. Agreed with @oranod about presence on the forum as the central community hub.
I think this requirement would bring other requirements like having good well-structured development and maintainer guidelines (probably defined by us in some part). Do we really want to regulate it too?
Anyway, I think to ensure the access it’d require granting admin access to us.
Whatever we decide, the projects on the ecosystem page should undergo periodic revisions.
In case, there are signs of abandonment, the maintainers could be pinged and,
if no response, the project will get removed from the page.
Also I think OSI approved licenses imply that succession can be done by forking a project and developing the fork instead.
Agreed with @flowerysong 's argument. @oranod yes, it takes time to ramp up but if this failure happens, the project will simply go away from the ecosystem page. The periodic revision will be needed anyway.
+1 it’s definitely a must. @briantist brought a good point about the evaluation. I think it’s hard to evaluate it not being a real user, so i’m +1 with just having something called “User guide” somewhere including README publicly available free of charge and registration.
This would first require to decide who and how will decide on the usefulness and other subjective requirements. Can be community vote or whatever but we should keep some possible decision-making mechanisms in mind while defining the requirements.
Agreed with @briantist. We shouldn’t put links to any lists we don’t maintain not to take any responsibility for their relevance. We could put in the ecosystem page a note that this is not a complete list of Ansible-related projects.
We shouldn’t imo use the same set of requirements for RH and non RH projects.
I don’t disagree with any of the RH-specific requirements you mentioned, but to me it feels like those requirements should be at the project level (a standard those projects use for themselves), rather than a set of alternate requirements that are part of the list project.
As a non-RHer, I don’t feel the need to distinguish between RH and non-RH projects on the list itself.
Part of my thinking here is that you have a great idea: with RH people involved in the community, there’s opportunity to demand higher standards from RH projects that we simply cannot impose on external projects, but I am wary of having a community project (as a whole) trying to be the enforcer of those standards.
I recognize that I may be missing some things and don’t feel fully confident in my reasoning, so I’m interested in hearing more thoughts about this from you and community.
)
Some first ideas:
)