Merge branch 'softwareunderground-main'

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,22 +1,50 @@
 <!-- Thank you for contributing to our list! -->
 <!-- Please write a DESCRIPTIVE TITLE for the pull request and commits. -->
 
-Project name:
 
-Project website/repository:
+__Project name:__
 
-License:
+__Project website/repository:__
 
+__License:__
+
+__Submission type:__
+<!-- Submission type can be one of "New Software Project", "New Data Repository", "New Tutorial or Cheat Sheet", "New Miscellaneous", or "Fix/update existing entry" -->
+
+
+<!-- In the following checklist, an empty check-box is "[ ]", a checked check-box is "[x]". You can also interactively click the boxes once the PR is submitted. -->
+
+## Checklist for all pull requests:
 <!-- If adding a project to the list, make sure it fulfills the following criteria. -->
-Checklist for new projects:
 
+<!-- Make sure it's "certified awesome"! -->
+- [ ] Project is [`certified awesome`](awesome.md)
+
+<!-- General requirements -->
 - [ ] The project is [open-source](https://opensource.org/licenses/alphabetical) and accessible.
 - [ ] Searched the existing entries to make sure this is not a duplicate.
 - [ ] Contains only a single addition (make separate PRs if adding more than one).
 - [ ] Added the link to the bottom of the relevant category.
-- [ ] Add icon from the `media/icon/` folder if applicable (like `![Python](media/icon/python.png)` ).
 - [ ] Created a new category only if necessary.
+
+<!-- Formatting criteria -->
+- [ ] Add icon from the `media/icon/` folder if applicable (e.g., `![Python](media/icon/python.png)` ).
 - [ ] Checked spelling and grammar.
 - [ ] Removed trailing whitespace and periods.
 - [ ] Confirm the dash – is not a minus -.
-- [ ] Used [title-casing](http://titlecapitalization.com) (AP style) for project name.
+- [ ] Used [title-casing](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case) (AP style) for project name.
+
+
+### Checklist for new software projects:
+
+- [ ] Link the code repository rather than the website/documentation
+- [ ] Installation instructions present
+- [ ] Documentation looks great
+- [ ] Examples or Tutorials to follow
+- [ ] Tests and Travis CI running
+
+
+### Checklist for new Data Repositories, Tutorials and Cheat Sheets, and Miscellaneous:
+
+- [ ] Easily accessible
+- [ ] Comprehensive and widely appealing

.github/workflows/link_checker.yml

@@ -0,0 +1,12 @@
+on: [push, pull_request]
+
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: lychee Link Checker
+        id: lychee
+        uses: lycheeverse/lychee-action@v1.0.8
+      - name: Fail if there were link errors
+        run: exit ${{ steps.lychee.outputs.exit_code }}

awesome.md

@@ -1,51 +1,149 @@
-# The awesome manifesto
+# Our Definition of Awesome
 
-If you want your list to be included on `awesome`, try to only include actual awesome stuff in your list. After all, it's a curation, not a collection.
+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)](https://joss.readthedocs.io/en/latest/review_criteria.html). 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](contributing.md) 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?**
 
-## Only awesome is awesome
+# Contents
+
+- [Open Licensing](#choose-an-appropriate-license)
+    - [Software](#software)
+    - [Non - Software](#non-software)
+    - [Unacceptable](#unacceptable-licenses)
+- [Project Community Guidelines](#project-community-guidelines)
+- [Publications and Cheat Sheets](#publicationsand-cheat-sheets)
+- [Datasets](#datasets)
+    - [Dataset Documentation](#dataset-documentation)
+    - [Download Instructions](#download-instructions)
+- [Software](#software)
+    - [Software Documentation](#software-documentation)
+        - [Readme](#readme)
+        - [Installation Instructions](#installation-instructions)
+        - [Examples and Tutorials](#examples-and-tutorials)
+        - [API Documentation](#api-documentation)
+    - [Software Tests](#software-tests)
+
+
+
+# Choose an appropriate license
+
+Need help?
+
+**http://choosealicense.com/**
+
+There should be an [Open Software Initiative](https://opensource.org/licenses/) or [Free Software Foundation](https://www.fsf.org/licensing/licenses/) approved license file for software included in the repository. Keep in mind that if you [haven't selected a license](http://choosealicense.com/no-license/), it very likely means the people are *not* allowed to reproduce, distribute or create derivative works.
+
+## Software
+Common licenses for software are [found here](http://choosealicense.com/):
+* [Apache License 2.0](https://opensource.org/licenses/Apache-2.0)
+* [BSD 3-Clause "New" or "Revised" license](https://opensource.org/licenses/BSD-3-Clause)
+* [BSD 2-Clause "Simplified" or "FreeBSD" license](https://opensource.org/licenses/BSD-2-Clause)
+* [GNU General Public License (GPL)](https://opensource.org/licenses/gpl-license)
+* [GNU Library or "Lesser" General Public License (LGPL)](https://opensource.org/licenses/lgpl-license)
+* [MIT license](https://opensource.org/licenses/MIT)
+
+## Non-Software
+Non-software typically use Creative Commons:
+* [CC0](https://creativecommons.org/publicdomain/zero/1.0/)
+* [CC-BY](https://creativecommons.org/licenses/by/4.0/).
+* [CC-BY-SA](https://creativecommons.org/licenses/by-sa/4.0/).
+* Code licenses like MIT, BSD, GPL, and so forth are **not** recommended for this type.
+
+## Unacceptable Licenses
+Some licenses that are ***not*** open and **cannot be included**:
+* [No license](http://choosealicense.com/no-license/)
+* [CC-BY-NC](https://creativecommons.org/licenses/by-nc/4.0/)
+* [CC-BY-ND](https://creativecommons.org/licenses/by-nd/4.0/)
+* [NASA Open Source Agreement](http://directory.fsf.org/wiki/License:NASA-OSA_v1.3)
+* [Microsoft's Shared Source CLI, C#, and Jscript License](http://directory.fsf.org/wiki/License:Ms-SS)
+* [Oculus Rift SDK License](http://directory.fsf.org/wiki/License:Oculus_VR_Rift_SDK_License)
+* More exhaustive lists: [Software](http://www.gnu.org/licenses/license-list.html#NonFreeSoftwareLicenses) and [Others](http://www.gnu.org/licenses/license-list.html#NonFreeDocumentationLicenses)
+
+| ▲ [Top](#our-definition-of-awesome) |
+| --- |
+
+# Project Community Guidelines
+
+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](#our-definition-of-awesome) |
+| --- |
+
+# Datasets
+
+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.
+
+## Dataset Documentation
+
+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.
+
+## Download Instructions
+
+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](#our-definition-of-awesome) |
+| --- |
+
+# Publications and Cheat Sheets
+
+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.
+
 
-Research if the stuff you're including is actually awesome. Only put stuff on the list that you or another contributor can personally recommend. You should rather leave stuff out than include too much.
+| ▲ [Top](#our-definition-of-awesome) |
+| --- |
 
-## Awesome badge
+# Software
 
-[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome)
+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.
 
-Add an awesome badge to the top of your list, right next to the title. [Example](https://github.com/sindresorhus/awesome-nodejs).
+## Software Documentation
 
-```md
-[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome)
-```
+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](https://en.wikipedia.org/wiki/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!
 
-## Comment on why something is awesome
+### Readme
+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.
 
-Apart from suggesting a particular item on your list, you should also inform your readers *why* it's on the list and how they will benefit from it.
+### Installation Instructions
 
-## Make it clear what the list is about
+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.
 
-Have a succinct description at the top of your readme. Make sure your list covers a certain scope and nothing else. Link to other awesome lists if you think they already cover a certain subject well enough.
+    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
 
-## Pay attention to grammar
+### Examples and Tutorials
 
-Ensure your list is grammatically correct, typo-free and has no Markdown formatting errors. This should also apply to pull requests.
+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. 
 
-## Choose an appropriate license
+### API Documentation
 
-Keep in mind that if you [haven't selected a license](http://choosealicense.com/no-license/), it basically means the people are *not* allowed to reproduce, distribute or create derivative works.
+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.
 
-[Creative Commons licenses](https://creativecommons.org/) are perfect for this purpose. **We would recommend [`CC0`](https://creativecommons.org/publicdomain/zero/1.0/).** Code licenses like MIT, BSD, GPL, and so forth are not recommended.
+    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
 
-## Include contribution guidelines
+## Software Tests
 
-People who are contributing to your list should have a clear understanding of how they should do so.
+> Untested code is broken code.
 
-If you don't feel like writing one from scratch, feel free to take our [contributing.md](contributing.md) and modify it to your own needs.
+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.
 
-## Stylize your list properly
+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.
 
-Create a [table of contents](https://github.com/sindresorhus/stuff/blob/master/toc-generators.md), organize the content into different categories, and use images if suitable. Ensure all entries are consistent (e.g. all entry descriptions end in a `.`).
+    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
 
-## Accept other people's opinion
 
-If you're an owner of the list, respect other people's opinion. If there are plenty of users not agreeing to your decision, give it a second thought.
+| ▲ [Top](#our-definition-of-awesome) |
+| --- |

contributing.md

@@ -39,7 +39,25 @@ It may however fail for the following reasons:
 * Redirection of link: Your link redirects somewhere else. In  this case, please use the
   final link after redirection.
 
-Clicking on the failing build (a red x) will take you to the TravisCI website.
-Look at the log to see what went wrong and what needs fixing.
+Clicking on the failing build (a red x) will take you to the TravisCI website. 
+You probably want to right click, so it opens in a new tab otherwise it can be difficult to go backwards.
+Look at the log to see what went wrong and what needs fixing. What is wrong is usually at the very bottom of the log.
 If none of this makes sense to you, let us know and we'll come in and guide you along to
 make the contribution a success.
+
+##### Fixing 301 Link Redirection Error
+Fixing a 301 link redirection error usually means (1) following the link to the TravisCI logs 
+(2) finding which link has changed. The logs will usually have both the old link and the new link 
+(3) going back to the README and selecting edit. (4) and searching for the old link 
+(5) replacing the old link with new link that TravisCI suggests. 
+
+If this is done within a pull request that exists and just ran a short time ago, 
+your changes will automatically trigger a new run of TravisCI, which should now pass all the tests.
+However, if it has been a while since last running TravisCI there could now be additional link changes to address.
+
+##### Edit Someone Else's Pull Request as an Admin
+It is fairly common for pull requests to get stopped due to the submitter not understanding how to deal with TravisCI issues. In this case, the easiest way to edit their pull request to make corrections is to (1) go to the pull request (2) click on the `files changed` tab on the right (3) click on the three dots in the upper right corner of a file's window (4) select edit file. After you make edits, the changes will appear as commits by you in their pull request. This will also usually trigger the TravisCI job to run again. Although you could technically clone their pull request, this method is usually easier.
+
+##### Getting TravisCI to Run Again
+If you need TravisCI to run again but can't figure out how. Go to a file that doesn't matter, add an extra line. 
+Go back to that file and then edit away that line. This will trigger the pull request to run TravisCI again.