-
Notifications
You must be signed in to change notification settings - Fork 481
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
What defines "awesome"? #86
Comments
In the beginning we left it intentionally vague, trusting the community to be self regulating. Now that the list has grown to what appears to be a critical site, I totally agree with your point that we may want to specify this further. However, #74 also shows that our PR checklist is working quite well as a filter. I would like to see a project with good documentation. That's something easy to check. Installable... Well... How do we check? Right now @leouieda is doing a ton of work and I chip in when I can. I figure for both installing and trying out these submissions is near impossible. Contributing guide like JOSS needs? Awesome projects are open to contributions, right? Or is that over the top? |
How about tests as well? |
I agree with both of you that we should probably have clearer guidelines. What about adopting the JOSS criteria? We could start with those and modify the language a bit. This could be part of the PR checklist and should be included in the README somewhere. From https://joss.readthedocs.io/en/latest/review_criteria.html#review-items Software licenseThere should be an OSI approved license included in the repository. Common licenses such as those listed on choosealicense.com are preferred. Note there should be an actual license file present in the repository not just a reference to the license.
DocumentationThere should be sufficient documentation for you, the reviewer to understand the core functionality of the software under review. A high-level overview of this documentation should be included in a README file (or equivalent). Installation instructionsThere should be a clearly-stated list of dependencies. Ideally these should be handled with an automated package management solution.
Example usageThe authors should include examples of how to use the software (ideally to solve real-world analysis problems). API documentationReviewers should check that the software API is documented to a suitable level.
Community guidelinesThere should be clear guidelines for third-parties wishing to:
FunctionalityReviewers are expected to install the software they are reviewing and to verify the core functionality of the software. TestsAuthors are strongly encouraged to include an automated test suite covering the core functionality of their software.
|
Including things in the PR checklist is really good, I agree.
I agree with OSI approved. But cheatsheets can just have the approved CC-BY tag I think.
Agree. And it should be looking awesome.
Agree. Requirements and installable seem really good.
I think that is like a bonus points point.
Can we shoehorn that into general documentation?
Like it.
Yeah that would clearly be awesome.
I think it should only be suggested if it's working.
Probably a good idea... Didn't check for that yet.
I think it could be a bit more software agnostic, to invite other contributions like datasets and reference material. |
I like the JOSS suggestions. Suggest they should be clearly worded as guidelines of what "Awesome" looks like more than requirements for entry? Both due to the wider range of what is accepted here compared to JOSS and the fact that we probably want to be a step below JOSS in terms of what's allowed. Additionally, if people feel they have to do a lot of work to submit a change request to this repo, they're less likely to do so. Maybe have these criteria under a separate "need more help determining if something is awesome, go here". That way they can be used for clarification, and back up when declining pull requests, but don't pour cold water on enthusiastic participation. |
I've made a stab at it in #88. Would love for you folks to just go in and edit it to make it certified awesome. We can then go on to modify the PR list, when we have this done. I see it being something like:
|
Can new or obscure projects (as in, with little real-world usage) that satisfy all/most other criteria qualify as "awesome"? If yes I'd like to plug tilesegy, a small Segyio-like project I published recently. |
I'm leaning yes? Would be great to hear opinions of anyone else too. Can you add a bit more in the README about why someone would use it and what they would use it to do? That's probably a lot more obvious to you then others. |
The description in https://github.com/softwareunderground/awesome-open-geoscience/blame/master/awesome.md#L9 is vague to me... I'm curious if there is a checklist of what might make software "awesome" and ready to be added to this list?
I'm asking because I've seen a few projects show up in PRs that maybe aren't as awesome as some of the projects listed here.
Example
Compare GemPy (on the awesome list) and a proposed change like that in #74
GemPy is pretty awesome in my opinion - it has excellent documentation, a new-user-friendly README, lots of tutorials for new users to get up an running, and it's generally accessible (installable via a package manager like
pip
).Meanwhile I’m struggling to find these aspects of the project in #74 which proposes adding MB-System. This software has a difficult to read/understand README, no API documentation (or at least after clicking around their website, I did not immediately see it), and no(?) existing examples for new users to get their hands dirty. Although it does appear to be generally accessible (installable using Homebrew)
The text was updated successfully, but these errors were encountered: