Skip to content

Commit

Permalink
Added exercises in Episodes #3 and #5
Browse files Browse the repository at this point in the history 
Specifically, added the following (according to issue #102):
- license conflicts and relicensing
- why is discoverability of your software important
- FAIR software and top 10 FAIR software things
  • Loading branch information
@fpsom
fpsom committed Oct 4, 2019
1 parent 3e496d3 commit 6d4e5f7
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 23 deletions.
39 changes: 22 additions & 17 deletions _episodes/03-use-license.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ keypoints:

### What is a copyright?

* Copyright is a legal right over the creative expression of an idea or an intellectual work. It grants the creator of an original work exclusive rights to determine and decide whether, and under what conditions, this original work may be used by others.
* Copyright is a legal right over the creative expression of an idea or an intellectual work. It grants the creator of an original work exclusive rights to determine and decide whether, and under what conditions, this original work may be used by others.
* Copyright is automatically attached to every novel expression of an idea, including a poem or a blog entry, for a certain amount of years, typically from 50 to 100 years after the idea creator dies (depending on the jurisdiction). That is, the law assumes that as the author of your code, you have a say in what others can do with it.
* In particular, the code that you write is copyrighted by default in the most restrictive way. This implies that nobody, except you, can use, modify, create derivative works and distibute your code.
* If you infringe on someone's copyright you may be in the situation of having to pay reasonable damages.
Expand All @@ -34,9 +34,9 @@ Fair use (*Comparison*, *criticism* and *quotation* with citation) is an excepti
> ### Challenge
>
> For each one of the three scenarios below, answer yes or no to the question.
>
>
> 1. **Scenario:** you receive a sticker and your friends want a copy.
>
>
> **Question:** can you make a copy of the sticker and sell the copy to your friends?
>
> 2. **Scenario:** you receive a script from your supervisor asking you to modify it to analyse a different type of input data.
Expand All @@ -48,7 +48,7 @@ Fair use (*Comparison*, *criticism* and *quotation* with citation) is an excepti
> **Question:** are you allowed to use the photos that you downloaded for your machine learning algorithm?
{: .challenge}

### What a licence does
### What a licence does

A licence is an official permission to do, use, or own something. Basically, a licence waives parts of a copyright by defining terms and conditions for the usage of a product.
A shorthand definition of license is "a promise by the licensor not to sue licensees" if they comply with the licence terms and conditions.
Expand Down Expand Up @@ -99,7 +99,7 @@ Permissive licenses, as opposed to copyleft licenses, does not enforce that deri
> ### Challenge 1
>
> Work in pairs. Pick one item from the list below. Discuss with your partner what would be the implications to your project if one of the third-party libraries that you are considering to use, has the fragment mentioned in the selected item as part of their license.
>
>
> 1. "Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination."
>
> Source: GNU Classpath's License
Expand Down Expand Up @@ -139,7 +139,12 @@ Once added, a licence and all future versions of the software, will be under tha

> ### Note: Dual License
>
> Some software that have comercial potential adopt a dual license model. They have a version of the code under the GNU General Public License that is freely available to everyone, but they also offer a proprietary version of the code in exchange of some cash. If you decide to adopt this business model, you must be very careful to correctly collect copyright transfer from all contributors to you.
> Some software that have commercial potential adopt a dual license model. They have a version of the code under the GNU General Public License that is freely available to everyone, but they also offer a proprietary version of the code in exchange of some cash. If you decide to adopt this business model, you must be very careful to correctly collect copyright transfer from all contributors to you.
{: .callout}

> ### Note: License conflicts and Relicensing
>
> Given the complexity of software and the multitude of dependencies that occur, it's quite possible to encounter a situation where the software licenses of some of the dependencies are incompatible to each other (i.e. there exist License conflicts). This creates a strong issue, especially when building software in the Open Science community, as these requirements can make it impossible to combine source code or content of several software works to create a new combined one. In order to move forward in these cases, the offending components need to be relicensed to a more compatible License.
{: .callout}

In principle, you can create your own bespoke licence, it's your right. However, we strongly discourage it, unless you have appropriate legal background. You are helping the users to understand the licence over your code or data by adopting an existing, widely described licence which better suits with your creation. So, users do not have to analyze the legal details of the licence to understand it.
Expand All @@ -151,12 +156,12 @@ https://choosealicense.com/

By including an open source license in your repository, it makes easier for other people to contribute. Most of the projects places their license information in a file named `LICENSE` (`LICENSE.txt` or `LICENSE.md` or `LICENSE.rst` or `COPYING`, `COPYING.txt`, `COPYING.md`, `COPYING.rst` are also used) in the root of the repository.

> ## Challenge
>
> ## Challenge
>
> Add the previously selected license to your GitHub repository
>
>
> > ## Solution
> >
> >
> > Via the GitHub interface for an already existing repository
> > 1. On GitHub, navigate to the main page of the repository.
> > 2. Click on `Create new file` button above the file list
Expand All @@ -166,8 +171,8 @@ By including an open source license in your repository, it makes easier for othe
> > 6. Check that the license terms correspond to the one
> > 7. Click on `Review and submit` button
> > 8. Commit the file
> >
> > Locally:
> >
> > Locally:
> > 1. Navigate to the root of the repository
> > 2. Open your favorite text editor with a new file
> > 3. Go to https://choosealicense.com
Expand All @@ -176,8 +181,8 @@ By including an open source license in your repository, it makes easier for othe
> > 6. Paste the content in the text editor
> > 8. Save the file as `LICENSE.md`
> > 9. Commit the added file
> >
> >
> >
> >
> > Via the GitHub interface for a new repository
> > 1. Start creation of a new repository
> > 2. Click on `Add a license`
Expand All @@ -186,8 +191,8 @@ By including an open source license in your repository, it makes easier for othe
{:.challenge}

> ## Notes: Other places for license
>
>
> Some projects also include the license in every individual file. This approach is appropriate when the project is a collection of small scripts that work independently.
>
> Also, some projects have a short paragraph naming the license they use the README file with, for example, a note saying "This project is licensed under the terms of the MIT license.".
>
> Also, some projects have a short paragraph naming the license they use the README file with, for example, a note saying "This project is licensed under the terms of the MIT license.".
{: .callout}
39 changes: 33 additions & 6 deletions _episodes/05-use-registry.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,21 @@ For some more information and examples, [follow this link](https://web.archive.o

For the software case, we have defined metadata as "_a set of data that describes and gives information about software with the purpose of make it findable/discoverable_".

> ## Exercise: Why do we want software to be findable/discoverable
> #### Time 5 minutes
>
> Before start working with metadata, it's worth thinking about the importance of Software being findable. Work in small groups and discuss how many times you have tried to look-up and use software that has been listed and/or described in a paper. How many times have you encountered issues? How easy was it to find it in the first place? How often have you been successful in locating it?
>
> By the end of this exercise, you should be able to have a better understanding of the necessity of software findability.
>
> > ## Solution
> >
> > There are a lot of papers that do use software but either do not cite it, nor do they provide a link to the software itself. In other cases, only a name is provided (with no link or other information). All these are examples were the software is indicated, but actually looking it up is a difficult task by itself.
> >
> {: .solution}
{: .discussion}

Now that we have established the need for software to be discoverable, let's focus on **how** we can make it discoverable. Using metadata is an excellent way towards this direction.

> ## Exercise: Think about metadata
> #### Time 5 minutes
Expand Down Expand Up @@ -232,16 +247,28 @@ By adding good enough metadata to our research software, we are directly support
> {: .solution}
{: .challenge}

## Example

Now that you have been exposed to the 4 Open Source Software recomendations. Here is an example to see how all of these recomendations come together.
Looking at all four FAIR principles (Findability, Accessibility, Interoperability and Reusability), it may be worth checking out the [Top 10 FAIR Data & Software Things](https://librarycarpentry.org/Top-10-FAIR/). These are brief guides (stand alone, self paced training materials), called "Things", that can be used by the research community to understand how they can make their research (data and software) more FAIR, with each discipline/topic having its own specific list.

### OpenSNP
For Research Software, the [Top 10 FAIR Data & Software "Things"](https://librarycarpentry.org/Top-10-FAIR/2018/12/01/research-software/) are briefly the following:
1. Create a description of your software
2. Register your software in a software registry
3. Get and use a unique and persistent identifier for your software
4. Make sure that people can download your software
5. Explain the functionality of your software
6. Use standard (community agreed) formats for inputs and outputs
7. Document your software
8. Give your software a license
9. State how to cite your software
10. Follow best practices for software development

The [openSNP](https://opensnp.org/) is an Open Source Software project which makes use of other Open Source Software. We have selected this as an example because it complies with all 4 recommendations.
As you can see, all of them have been briefly discussed in this lesson, and it is definitely worth reading through the full short guide yourselves.

The [openSNP](https://opensnp.org/) project is licensed under the [MIT License](https://github.com/openSNP/snpr/blob/master/LICENSE.md), the code is at [GitHub](https://github.com/openSNP/snpr). The data is donated into the public domain using [CC0 1.0](http://creativecommons.org/publicdomain/zero/1.0/). The CSS of openSNP is provided by [Bootstrap](http://twitter.github.com/bootstrap/), from Twitter and is licensed under the [Apache License v2.0](http://www.apache.org/licenses/LICENSE-2.0), the search icon comes from [glyphicons](http://glyphicons.com/). If you are interested in this project here are the [contribution guidelines](https://github.com/openSNP/snpr/blob/master/CONTRIBUTING.md). Also, find the [registry of openSNP in bio.tools](https://bio.tools/openSNP) to see publication, citations and how to credit the software.
## Example

Now that you have been exposed to the 4 Open Source Software recommendations. Here is an example to see how all of these recommendations come together.

### OpenSNP

The [openSNP](https://opensnp.org/) is an Open Source Software project which makes use of other Open Source Software. We have selected this as an example because it complies with all 4 recommendations.

The [openSNP](https://opensnp.org/) project is licensed under the [MIT License](https://github.com/openSNP/snpr/blob/master/LICENSE.md), the code is at [GitHub](https://github.com/openSNP/snpr). The data is donated into the public domain using [CC0 1.0](http://creativecommons.org/publicdomain/zero/1.0/). The CSS of openSNP is provided by [Bootstrap](http://twitter.github.com/bootstrap/), from Twitter and is licensed under the [Apache License v2.0](http://www.apache.org/licenses/LICENSE-2.0), the search icon comes from [glyphicons](http://glyphicons.com/). If you are interested in this project here are the [contribution guidelines](https://github.com/openSNP/snpr/blob/master/CONTRIBUTING.md). Also, find the [registry of openSNP in bio.tools](https://bio.tools/openSNP) to see publication, citations and how to credit the software.

0 comments on commit 6d4e5f7

Please sign in to comment.