[Reuse] Draft of REUSE tutorial
Carmen Bianca Bakker
carmenbianca at fsfe.org
Thu Mar 14 15:55:06 UTC 2019
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
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
- 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.
diff --git a/content/reuse.en.md b/content/reuse.en.md
index d10a0c1..216ca41 100644
@@ -4,9 +4,15 @@ subtitle: "!!!THIS IS A ROUGH DRAFT!!!"
+# 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:
@@ -26,19 +32,16 @@ project/
-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
# 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
+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
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 833 bytes
Desc: This is a digitally signed message part
More information about the Reuse