Clarify contribution guidelines/"awesomeness" criteria #714

New Issue

GiteaMirror · 2025-11-19T20:58:39-06:00

GiteaMirror commented

2025-11-19 20:58:39 -06:00

Originally created by @nodiscc on GitHub (Mar 1, 2023).

Followup to https://github.com/awesome-foss/awesome-sysadmin/pull/357 (add PiVPN)

@nodiscc

curl | bash

Software that uses this installation method used to be rejected under the previous maintainer (https://github.com/awesome-foss/awesome-sysadmin/pulls?q=is%3Apr+pivpn+is%3Aclosed). This guideline was never written down but I don't want to change the way the list is maintained right now (it's currently on minimal maintenance mode https://github.com/awesome-selfhosted/awesome-selfhosted/issues/2482, I'm just doing some cleanup).

I know I would personally never use this method (I understand it's just a matter of downloading the install script first, inspecting it, then running it, but then the documentation should mention it explicitly).

This is more of an open question, what guidelines should be added to keep the list high quality? From the past list of issues I remember these ideas:

the program must be mature enough (e.g. old enough to be in Debian Stable)

usable in a professional setup

have a decently sized community of users or contributors

no curl | bash

...?

Feedback welcome.

@jadolg

IMO the curl | bash thing is a bit arbitrary.
There are other installation methods listed right there and it's not like you can't read what you are installing if you actually want to.
I know you "should not" just curl | bash for security reasons, but most people (even being able to read what they are going to execute) are not going to analyze a thing.

@xrat

I'd like to add a reminder to the discussion of list quality, namely the distinction of sysadmin vs. superuser vs. beginner. At least 1 of these is supposed to know the implications of curl | bash.

@nodiscc

distinction of sysadmin vs. superuser vs. beginner

In my opinion this list should stay a resource intended for professional sysadmins, or at least people striving to implement setups of professional quality.

you "should not" just curl | bash for security reasons, but most people are not going to analyze a thing.

Which is a huge no-go in professional environments (not analyzing what's being run). Hence software for which curl | bash is the only documented installation method should not be included, in my opinion.

Other opinions regarding criteria for inclusion are welcome (see comments above).

Related https://github.com/awesome-foss/awesome-sysadmin/pull/429

@xrat

Hence software for which curl | bash is the only documented installation method should not be included, in my opinion.

I understand your point of view, and I do not disagree, however, as a professional sysadmin I am quite able to appreciate installation instructions based on a (furthermore likely well-tested) shell script. In fact, it so happened that I got notice of PiVPN thanks to this pull request. I reviewed its install.sh and went with it. I have to say, though, that its 3k lines is not a trivial perusal.

Concluding, while I personally don't mind curl | bash, I agree it should not be the only documented installation method.

@OckhamOdyssey

I don't understand why not accept the PR just because they document the curl | bash. PiVPN is secure by default and have pretty good scripts to manage the clients certifications, specially for large number of users. They have the git clone option.

but most people (even being able to read what they are going to execute) are not going to analyze a thing.

If we are going to follow that logic, thinking in the very beginners users, we should delete so many programs of the list because the documentation doesn't say "remember to check the code before executing".

@nodiscc

The criteria from OpenSSF Best Practices are good indicators of quality in FOSS projects. You can see a list of projects and their scores at https://bestpractices.coreinfrastructure.org/en/projects.

Note that the use of curl | bash is NOT explicitely forbidden by these guidelines. The closest thing I could find is

The project MUST use a delivery mechanism that counters MITM attacks. Using https or ssh+scp is acceptable.

So if we go by this, curl | bash would be acceptable as long as the URL is a HTTPS one. There is another guideline in the silver level criteria that states

The project MUST cryptographically sign releases of the project results intended for widespread use, and there MUST be a documented process explaining to users how they can obtain the public signing keys and verify the signature(s). The private key for these signature(s) MUST NOT be on site(s) used to directly distribute the software to the public.

Of course curl | bash installation scripts imply the absence of cryptographic signatures, but a lot of projects using other installation methods do not provide signatures either, so if we started requiring this, a lot of software currently present in the list would not qualify.

In light of all this, and the other comments here, I don't think curl | bash as recommended installation method automatically makes the software "not awesome". /cc @n1trux

We should still find clear criteria for what is considered "awesome enough" or not. Feedback still welcome.

@nodiscc

The review in https://github.com/awesome-foss/awesome-sysadmin/pull/449 yielded good results, I asked a few questions which resulted in constructive answers from @kosli:

Have you used it? For how long?
Is this in a personal or professional setup?
How many devices do you manage with it?
Biggest pros/cons compared to other solutions?
Any other comments about your use case, things you've found excellent, limitations you've encountered... ?

I am using it since a few weeks in a professional setup and I am very happy and looking into contributing myself as I want to make some features that I need.
Currently I have only 5 routers (PC engines apu boards) in the system, but have ~400 devices running in my own system that I will migrate over time into OpenWISP.a
I accidentally found OpenWISP when I was looking into a new OS for my routers (OpenWRT) and I am very impressed by the feature-rich, well-build platform that can easily be extended.

I think this is the kind of questions we could include in the pull request template.

@nodiscc

Good results as well in https://github.com/awesome-foss/awesome-sysadmin/pull/457 and https://github.com/awesome-foss/awesome-sysadmin/pull/453. I'll make a Pull Request to add these questions to the template (done: https://github.com/awesome-foss/awesome-sysadmin/pull/459), and move this discussion to a dedicated issue.

Originally created by @nodiscc on GitHub (Mar 1, 2023). Followup to https://github.com/awesome-foss/awesome-sysadmin/pull/357 (add PiVPN) ------ @nodiscc >> `curl | bash` >Software that uses this installation method used to be rejected under the previous maintainer (https://github.com/awesome-foss/awesome-sysadmin/pulls?q=is%3Apr+pivpn+is%3Aclosed). This guideline was never written down but I don't want to change the way the list is maintained right now (it's currently on minimal maintenance mode https://github.com/awesome-selfhosted/awesome-selfhosted/issues/2482, I'm just doing some cleanup). >I know I would personally never use this method (I understand it's just a matter of downloading the install script first, inspecting it, then running it, but then the documentation should mention it explicitly). >This is more of an open question, what guidelines should be added to keep the list high quality? From the past list of issues I remember these ideas: >- the program must be mature enough (e.g. old enough to be in Debian Stable) >- usable in a professional setup >- have a decently sized community of users or contributors >- no `curl | bash` >- ...? >Feedback welcome. ----------------- @jadolg >IMO the `curl | bash` thing is a bit arbitrary. >There are other installation methods listed right there and it's not like you can't read what you are installing if you actually want to. >I know you "should not" just `curl | bash` for security reasons, but most people (even being able to read what they are going to execute) are not going to analyze a thing. ---------------- @xrat >I'd like to add a reminder to the discussion of list quality, namely the distinction of sysadmin vs. superuser vs. beginner. At least 1 of these is supposed to know the implications of `curl | bash`. ---------- @nodiscc >> distinction of sysadmin vs. superuser vs. beginner >In my opinion this list should stay a resource intended for professional sysadmins, or at least people striving to implement setups of professional quality. >> you "should not" just curl | bash for security reasons, but most people are not going to analyze a thing. >Which is a huge no-go in professional environments (not analyzing what's being run). Hence software for which `curl | bash` is the only documented installation method should not be included, in my opinion. >Other opinions regarding criteria for inclusion are welcome (see comments above). > Related https://github.com/awesome-foss/awesome-sysadmin/pull/429 ---------- @xrat >> Hence software for which `curl | bash` is the only documented installation method should not be included, in my opinion. >I understand your point of view, and I do not disagree, however, as a professional sysadmin I am quite able to appreciate installation instructions based on a (furthermore likely well-tested) shell script. In fact, it so happened that I got notice of PiVPN thanks to this pull request. I reviewed its `install.sh` and went with it. I have to say, though, that its 3k lines is not a trivial perusal. >Concluding, while I personally don't mind `curl | bash`, I agree it should not be the only documented installation method. ----------- @OckhamOdyssey >I don't understand why not accept the PR just because they document the `curl | bash`. PiVPN is secure by default and have pretty good scripts to manage the clients certifications, specially for large number of users. They have the [`git clone`](https://github.com/pivpn/pivpn#method-3-clone-repo) option. >> but most people (even being able to read what they are going to execute) are not going to analyze a thing. >If we are going to follow that logic, thinking in the very beginners users, we should delete so many programs of the list because the documentation doesn't say "remember to check the code before executing". -------------------- @nodiscc >The criteria from [OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/en/projects/1) are good indicators of quality in FOSS projects. You can see a list of projects and their scores at https://bestpractices.coreinfrastructure.org/en/projects. >Note that the use of `curl | bash` is NOT explicitely forbidden by these guidelines. The closest thing I could find is >> The project MUST use a delivery mechanism that counters MITM attacks. Using https or ssh+scp is acceptable. >So if we go by this, `curl | bash` would be acceptable as long as the URL is a HTTPS one. There is another guideline in the [silver level criteria](https://bestpractices.coreinfrastructure.org/en/projects/2231?criteria_level=1#security) that states >> The project MUST cryptographically sign releases of the project results intended for widespread use, and there MUST be a documented process explaining to users how they can obtain the public signing keys and verify the signature(s). The private key for these signature(s) MUST NOT be on site(s) used to directly distribute the software to the public. >Of course `curl | bash` installation scripts imply the absence of cryptographic signatures, but a lot of projects using other installation methods do not provide signatures either, so if we started requiring this, a lot of software currently present in the list would not qualify. >In light of all this, and the other comments here, I don't think `curl | bash` as recommended installation method automatically makes the software "not awesome". /cc @n1trux >We should still find clear criteria for what is considered "awesome enough" or not. Feedback still welcome. ------------------------ @nodiscc >The review in https://github.com/awesome-foss/awesome-sysadmin/pull/449 yielded good results, I asked a few questions which resulted in constructive answers from @kosli: Have you used it? For how long? Is this in a personal or professional setup? How many devices do you manage with it? Biggest pros/cons compared to other solutions? Any other comments about your use case, things you've found excellent, limitations you've encountered... ? >> I am using it since a few weeks in a professional setup and I am very happy and looking into contributing myself as I want to make some features that I need. >> Currently I have only 5 routers (PC engines apu boards) in the system, but have ~400 devices running in my own system that I will migrate over time into OpenWISP.a >> I accidentally found OpenWISP when I was looking into a new OS for my routers (OpenWRT) and I am very impressed by the feature-rich, well-build platform that can easily be extended. >I think this is the kind of questions we could include in the pull request template. ----------------------- @nodiscc >Good results as well in https://github.com/awesome-foss/awesome-sysadmin/pull/457 and https://github.com/awesome-foss/awesome-sysadmin/pull/453. I'll make a Pull Request to add these questions to the template (done: https://github.com/awesome-foss/awesome-sysadmin/pull/459), and move this discussion to a dedicated issue.

GiteaMirror added the curation discussion feedback needed help wanted labels 2025-11-19 20:58:39 -06:00

GiteaMirror commented

2025-11-19 20:58:41 -06:00

@nodiscc commented on GitHub (Mar 29, 2025):

@Rabenherz112 @Technetium1 do you want to be added as maintainers for this repo?

I didn't have much time to maintain it/review PRs lately. Most of the software submitted is, in my opinion, too young to qualify, or not "true" FOSS (tight integration with non-free SaaS), not sufficiently maintained/not enough contributors, or the submissions are made by the project maintainers themselves, which is against contribution guidelines.

The understanding with the previous maintainer (@n1trux) at the time of ownership transfer was that we'd keep this a list of "boring" technology. Or at least that we'd be extremely conservative and opinionated about what gets added (not "awesome" -> rejected).

The criteria discussed above are still not decided upon - but if you agree, and there is a majority of approvals (2) on a given PR, I'd also approve and merge them.

The alternative is leaving the list ~~rot~~ as-is for the time being.

@nodiscc commented on GitHub (Mar 29, 2025): @Rabenherz112 @Technetium1 do you want to be added as maintainers for this repo? I didn't have much time to maintain it/review PRs lately. Most of the software submitted is, in my opinion, too young to qualify, or not "true" FOSS (tight integration with non-free SaaS), not sufficiently maintained/not enough contributors, or the submissions are made by the project maintainers themselves, which is against contribution guidelines. The understanding with the previous maintainer (@n1trux) at the time of ownership transfer was that we'd keep this a list of "[boring](https://mcfunley.com/choose-boring-technology)" technology. Or at least that we'd be extremely conservative and opinionated about what gets added (not "awesome" -> rejected). The criteria discussed above are still not decided upon - but if you agree, and there is a majority of approvals (2) on a given PR, I'd also approve and merge them. The alternative is leaving the list ~~rot~~ as-is for the time being.

GiteaMirror commented

2025-11-19 20:58:41 -06:00

@Technetium1 commented on GitHub (Mar 30, 2025):

@nodiscc Yes, I am interested in helping where feasible. I would like to see this list survive. I support the notion of being picky about additions as well.

@Technetium1 commented on GitHub (Mar 30, 2025): @nodiscc Yes, I am interested in helping where feasible. I would like to see this list survive. I support the notion of being picky about additions as well.

GiteaMirror commented

2025-11-19 20:58:41 -06:00

@Rabenherz112 commented on GitHub (Apr 5, 2025):

In general, I'd be open to being added as a maintainer. However, given my limited availability, my primary focus would still be on awesome-selfhosted rather than awesome-sysadmin.

Additionally, I'm not fully clear on what exactly qualifies for inclusion in this list and what doesn't. I've read both this Issue and the PR template, but beyond the mentioned hard points there, I'm unsure about other specific criteria there is to what out for. For instance, how long should a software project exist before being considered mature enough? How many active maintainers should it have (obviously more than one)? What other indicators are relevant to deciding whether something is "boring" technology suitable for inclusion here?

I think, it would be helpful if we could review some of the current open PRs together, just so I can better understand the intended criteria and scope. To be honest, this uncertainty was the main reason I stepped back from reviewing or submitting PRs here as well.

@Rabenherz112 commented on GitHub (Apr 5, 2025): In general, I'd be open to being added as a maintainer. However, given my limited availability, my primary focus would still be on `awesome-selfhosted` rather than `awesome-sysadmin`. Additionally, I'm not fully clear on what exactly qualifies for inclusion in this list and what doesn't. I've read both this Issue and the PR template, but beyond the mentioned hard points there, I'm unsure about other specific criteria there is to what out for. For instance, how long should a software project exist before being considered mature enough? How many active maintainers should it have (obviously more than one)? What other indicators are relevant to deciding whether something is "boring" technology suitable for inclusion here? I think, it would be helpful if we could review some of the current open PRs together, just so I can better understand the intended criteria and scope. To be honest, this uncertainty was the main reason I stepped back from reviewing or submitting PRs here as well.

GiteaMirror commented

2025-11-19 20:58:41 -06:00

@Technetium1 commented on GitHub (Apr 7, 2025):

Is it agreeable to drop all software that is no longer FOSS? An example is https://github.com/awesome-foss/awesome-sysadmin/pull/607

Expect more activity from me in the near future. I have been hugely affected by the ice storms in Michigan, and the power grid is not yet rebuilt.

@Technetium1 commented on GitHub (Apr 7, 2025): Is it agreeable to drop all software that is no longer FOSS? An example is https://github.com/awesome-foss/awesome-sysadmin/pull/607 Expect more activity from me in the near future. I have been hugely affected by the ice storms in Michigan, and the power grid is not yet rebuilt.

GiteaMirror commented

2025-11-19 20:58:42 -06:00

@Rabenherz112 commented on GitHub (Apr 7, 2025):

Is it agreeable to drop all software that is no longer FOSS? An example is https://github.com/awesome-foss/awesome-sysadmin/pull/607

Since this list is especially for open-source software, I think anything that got a license change and is no longer FOSS should be removed since it doesn't fit in the scope of this list anymore.

@Rabenherz112 commented on GitHub (Apr 7, 2025): > Is it agreeable to drop all software that is no longer FOSS? An example is https://github.com/awesome-foss/awesome-sysadmin/pull/607 Since this list is especially for open-source software, I think anything that got a license change and is no longer FOSS should be removed since it doesn't fit in the scope of this list anymore.

GiteaMirror commented

2025-11-19 20:58:42 -06:00

@Ki-er commented on GitHub (Apr 7, 2025):

I agree with the above. Removal is better than leaving it and keeping the list maintained. This list potentially has unmaintained projects. I would say these should be removed too to keep the list awesome.

@Ki-er commented on GitHub (Apr 7, 2025): I agree with the above. Removal is better than leaving it and keeping the list maintained. This list potentially has unmaintained projects. I would say these should be removed too to keep the list `awesome`.

GiteaMirror commented

2025-11-19 20:58:42 -06:00

@Technetium1 commented on GitHub (Apr 7, 2025):

I will be doing a full check for abandoned, unmaintained, and non-FOSS projects before completing #611.

@Technetium1 commented on GitHub (Apr 7, 2025): I will be doing a full check for abandoned, unmaintained, and non-FOSS projects before completing #611.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/awesome-sysadmin#714