Hello kind people,
I have created a draft of the tutorial. Going into the tutorial, I prioritised three things:
- Length (i.e., keep it short)
- Clarity of instructions
- Tangibility/relatability
Things I explicitly avoided (but might need to be mentioned elsewhere):
- Explaining how copyright and licensing works
- Explaining why this is important
- Explaining how SPDX and DEP-5 work
- Explaining rationales for REUSE decisions
- Explaining all the possible options from the spec
- Explaining that some licences might not be compatible, and you may occasionally need legal review from an expert
- Explaining that Free Software licences are the best licences
Specifically, I wanted to touch on these things going in:
- How to add licence
- How to mark files as being under a certain licence
- How to deal with files that cannot have headers
- How to deal with large directories
And so I ended up with http://carmenbianca.eu/en/reuse/;. If or when you have time, please let me know how it could be improved, or whether the general style of the tutorial is fitting at all. I am half-certain it would be much better with nice illustrations, but I am not very good at those.
With kindness, Carmen
Je ĵaŭ, 2019-02-21 je 14:32 +0100, Carmen Bianca Bakker skribis:
And so I ended up with http://carmenbianca.eu/en/reuse/;;;. If or when
I forgot: That page might be changed if I submit future versions. Here is a perma-link to the version as it is right now:
https://gitlab.com/carmenbiancablog/carmenbiancablog.gitlab.io/blob/5172caf5...
Hi Carmen, finally I got some time to read your work.
On 2/21/19 2:32 PM, Carmen Bianca Bakker wrote:
I have created a draft of the tutorial.
It is nicely written and I specially like the story telling. It makes it much more fun to read and understand.
Some remarks: - I would start with "By the end of this tutorial, all your files will clearly have their copyright and licensing marked." and a title like "Our Goal" (or something similar) - I would say "Assume that your project looks like this"... (This may also be clearer for non-native speakers; I was a little confused by "invariably") - I would add a description in parentheses for each abbreviation at its very first occurrence, for example, "FSF (Free Software Foundation)" - I would remove "(though they may also begin with ©)", because it is just a detail - I would remove ": Perhaps these files inexplicably break your build process.", because it is unlikely to happen and the sentence before already describes the reason somehow - "We followed the FSF's recommendations here." Maybe we could add a link to the recommendations? (...and, I would always use present tense) - "[...] ---the rest you can fill in as you like" <-- Is that true?
These is just my very rough brainstorming :-)
Any feedback welcome....
Cheers, Peter
--
Digital Technologies ICT Peter Moser
T +39 0471 066 672 p.moser@noi.bz.itmailto:p.moser@noi.bz.it
NOI Techpark Südtirol / Alto Adige A.-Volta-Straße / Via A. Volta, 13A I-39100 Bozen / Bolzano www.noi.bz.it https://www.noi.bz.it
Hi Peter,
Je ĵaŭ, 2019-03-14 je 10:53 +0000, Peter Moser (NOI Südtirol/Alto Adige) skribis:
Hi Carmen, finally I got some time to read your work.
On 2/21/19 2:32 PM, Carmen Bianca Bakker wrote:
I have created a draft of the tutorial.
It is nicely written and I specially like the story telling. It makes it much more fun to read and understand.
Thanks for the kind feedback :)
Some remarks:
- I would start with "By the end of this tutorial, all your files will clearly have their copyright and licensing marked." and a title like "Our Goal" (or something similar)
- I would say "Assume that your project looks like this"... (This may also be clearer for non-native speakers; I was a little confused by "invariably")
- I would add a description in parentheses for each abbreviation at its very first occurrence, for example, "FSF (Free Software Foundation)"
- I would remove "(though they may also begin with ©)", because it is just a detail
- I would remove ": Perhaps these files inexplicably break your build process.", because it is unlikely to happen and the sentence before already describes the reason somehow
- "We followed the FSF's recommendations here." Maybe we could add a link to the recommendations? (...and, I would always use present tense)
- "[...] ---the rest you can fill in as you like" <-- Is that true?
Agreed on all accounts, except the last. Kind of. I changed the phrasing to say "the rest is up to your discretion". The blurb text differs _a lot_ from project to project, so there are no hard rules there.
But you're right that "as you like" sounds too free-form. Some consideration needs to go into the blurb text, so I rephrased it.
On a separate note: I've just re-read the draft, and I notice two things missing. I'm half-sure they're worth adding:
- How to ignore files (i.e., mark them with CC0, because this gets asked a lot).
- How to lint the project automagically.
I think the second subject is worthy of being mentioned. The first subject might also be put in a FAQ, however.
In any case, find below the suggested patch for now.
With kindness, Carmen
diff --git a/content/reuse.en.md b/content/reuse.en.md index d10a0c1..216ca41 100644 --- a/content/reuse.en.md +++ b/content/reuse.en.md @@ -4,9 +4,15 @@ subtitle: "!!!THIS IS A ROUGH DRAFT!!!" type: "page" ---
+# Our goal + +By the end of this tutorial, all your files will clearly have their copyright +and licensing marked. + # Your project
-The directory of your project will invariably look something like this: +For the purpose of this tutorial, we will assume that the directory of your +project looks like this:
``` project/ @@ -26,19 +32,16 @@ project/ └── README.md ```
-By the end of this tutorial, all your files will clearly have their copyright -and licensing marked. - # A licence
The first thing you need is a licence. There are many good licences, but we -will pick the GNU General Public Licence v3.0. More than simply choosing a -licence, you need to put the licence in your project directory. +will pick the GNU General Public Licence v3.0 (GPL). More than simply choosing +a licence, you need to put the licence in your project directory.
In the [SPDX License List](https://spdx.org/licenses/), we notice that the SPDX Identifier of the licence is `GPL-3.0-or-later`. As such, we create a directory -`LICENSES`, and put the [licence text from the -FSF](https://www.gnu.org/licenses/gpl-3.0.txt) in a file called +`LICENSES`, and put the [licence text from the Free Software Foundation +(FSF)](https://www.gnu.org/licenses/gpl-3.0.txt) in a file called `GPL-3.0-or-later.txt`.
# Header blurb @@ -68,11 +71,11 @@ these files fall under that licence. We edit `src/main.c` as such: */ ```
-Only the first three lines are relevant for REUSE compliance---the rest you can -fill in as you like. We followed the FSF's recommendations here. +Only the first three lines are relevant for REUSE compliance---the rest is up to +your discretion. In this blurb, we use the text that the GPL proposes.
-- The first and second lines begin with `Copyright` (though they may also begin - with `©`) and record the publication years and copyright holders. +- The first and second lines begin with `Copyright` and record the publication + years and copyright holders.
- The third line begins with `SPDX-License-Identifier:` and is followed up by a [valid SPDX License Expression](https://spdx.org/specifications), typically @@ -123,8 +126,7 @@ files. You could edit the headers of these files yourself, but there are a lot of them, and you do not feel comfortable manually editing the translation files.
You could use `.license` files like you did for the images, but for some reason -you wish to opt against this: Perhaps these files inexplicably break your build -process. +you wish to opt against this.
For these files, you can use a configuration file. In your project root, create the file `.reuse/dep5`. This file uses Debian's
Die 14. 03. 19 et hora 16:55 Carmen Bianca Bakker scripsit:
It is nicely written and I specially like the story telling. It makes it much more fun to read and understand.
Agreed. It’s a good walk-through. Kudos!
- I would remove "(though they may also begin with ©)",
because it is just a detail
For a tutorial, I agree we should keep to just one choice, and perhaps mention at the end or in a footnote that there are other options that are also according to spec.
But, I would suggest to use “©” as the default. I realise there is some reluctance to change, but the fact remains that the copyright sign is the only thing that is written in actual law (incl. Berne Convention and several national copyright laws) consistently. Using the word “Copyright” is at best in accordance with copyright laws of English-speaking jurisdictions, where “©” is also accepted. If the tutorial is about best practices, we should apply them, and IMHO © is best practice.
In a similar vain, I think the years in the copyright should be entered just once as best practice. Year ranges will inevitabely eventually pop up the question on when one should update the year in the header. To which my personal opinion is that the year should reflect just the year when that file was created and then be ignored.
To keep this e-mail short, you can find my reasoning against the year range in the following thread: https://gitlab.com/tildes/tildes/issues/161#note_89229746
- How to ignore files (i.e., mark them with CC0, because this
gets asked a lot).
- How to lint the project automagically.
+1 on both
Also, it would make sense to point the actual SPDX license (plain)text repo as is done in the spec already: https://github.com/reusesoftware/reuse/pull/2
On that note, what should we do with the rest of the spec issues: https://github.com/reusesoftware/reuse/issues
cheers, Matija