If you want a project to be included in this awesome list, please check our definition of awesome. After all, it's a curation, not a collection. We base it loosely on the manifesto of the Journal of Open Source Software (JOSS). We say loosely, because their standards are higher. Our definition of awesome is more like guidelines to aim for and less like a strict set of rules. If you're new to coding and aren't sure if something qualifies, submit a pull request following the contribution guidelines and maintainers will help you out!
For now, we choose English as a common language for the list and as acceptable contributions to the list.
But what is awesome?
Need help?
There should be an Open Software Initiative or Free Software Foundation approved license file for software included in the repository. Keep in mind that if you haven't selected a license, it very likely means the people are not allowed to reproduce, distribute or create derivative works.
Common licenses for software are found here:
- Apache License 2.0
- BSD 3-Clause "New" or "Revised" license
- BSD 2-Clause "Simplified" or "FreeBSD" license
- GNU General Public License (GPL)
- GNU Library or "Lesser" General Public License (LGPL)
- MIT license
Non-software typically use Creative Commons:
- CC0
- CC-BY.
- CC-BY-SA.
- Code licenses like MIT, BSD, GPL, and so forth are not recommended for this type.
Some licenses that are not open and cannot be included:
- No license
- CC-BY-NC
- CC-BY-ND
- Microsoft's Shared Source CLI, C#, and Jscript License
- Oculus Rift SDK License
- More exhaustive lists: Software and Others
| ▲ Top |
|---|
Awesome projects make it easy to get involved with. Tell the community, how you would like your issues and pull requests and how you credit them when they contribute to the software, report issues or problems with the software or simply seek support.
| ▲ Top |
|---|
Awesome datasets need an open license and should be accessible. Ideally, they should be obtainable online, without sign-up. We appreciate that sometimes data portals with sign-ups are necessary. The sign-up for these portals must be automatic, meaning no long wait for response, and cannot limit usage of the data, meaning license restrictions that would make it non-open.
Awesome: Open downloadable data like an S3 bucket, API, kaggle dataset, or data.world dataset.
Awesome-ish (we get it, sometimes it's necessary): Data Portal with sign-up
Bad (not acceptable): Contact the authors / maintainers and ask for the thing in the back of the cabinet.
Awesome datasets contain a full description of the data included and information about acquisition, processing and ideally reference implementations of loading and visualization of the adata.
Awesome datasets make it easy to obtain the data. Tell the community, how they can best obtain the data in the most stable way.
| ▲ Top |
|---|
Awesome publications make it easy for the reader to navigate and obtain the information they need. These publications condense information in a unique way or offer a complete, exhaustive and comprehensive overview of a topic.
| ▲ Top |
|---|
Awesome software is easy to install, beautifully documented with great examples and fully tested to ensure functionality. We go into more detail in the following sections.
For a project to be awesome, documentation should be awesome. Look at our awesome list, we're trying to make this look good and people appreciate it. All of this was achieved with good formatting via Markdown in the Readme. If you really enjoy a project, but find the documentation is weak, that might be a great way to contribute to that project!
The readme of the repository should be well formatted and contain the gist of the project, and links all the following points, that ideally should be part of the larger documentation.
Awesome software makes it easy to use and include in your programming environment. In Python, Pypi and Conda make package management extremely powerful, ideally the software should be included in at least one of these. Gemfiles for Ruby, or NPM for nodejs are equally great for serving the software.
Awesome: A package management file such as a Gemfile or requirements.txt or equivalent
Awesome-ish (it's missing some of the magic): A list of dependencies to install
Bad (not acceptable): Reliance on other software not listed by the authors
Sometimes it can be a little non-obvious how to get the software started. An awesome project includes tutorials and examples how to use the software. This is another easy way to contribute to a project. If you think it is awesome, you've likely already made something that can be used as an example.
The API, or the collection of functionality should be described in the documentation. Making people guess if it's xy.from_csv, xy.read_csv, or xy.load_csv is less than Awesome. Better let them know and choose good defaults that can be changed regardless for all the edge cases that appear along the way.
Uber-Awesome: All functions methods have tutorials and examples.
Awesome: All functions/methods are documented including example inputs and outputs
Awesome-ish (it could be so much more awesome though): Core API functionality is documented
Bad (not acceptable): API is completely undocumented
Untested code is broken code.
Awesome projects make sure their code is working, ideally by automatic tests with full coverage of their software package. Remember many automatic Continuous Integration (CI) tools, offer discounts or free functionality to open source projects.
Tests can also be non-applicable for certain projects and are sometimes really hard to implement, if you're not sure whether the tests are acceptable, just let us know in the pull request and the maintainers will figure it out with you.
Uber-Awesome: Full coverage of all tests, automatically executed and instructions to test by hand
Awesome: An automated test suite hooked up to an external service such as Travis-CI or similar
Awesome-ish (If we're in a really good mood): Documented manual steps that can be followed to objectively check the expected functionality of the software
| ▲ Top |
|---|
This guideline is cited from awesome-open-geoscience