foundata / guidelines Goto Github PK

also interesting: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/

We often provide smaller tools and plugins where automatically release-tarballs are more then enough. When creating a release, Github creates a zip and a tar archive (the so called zipball and tarball), you can also get them via specific URLs:

https://api.github.com/repos/<user|org>/<repo>/tarball
https://api.github.com/repos/<user|org>/<repo>/zipball
https://api.github.com/repos/<user|org>/<repo>/tarball/<tag>
https://api.github.com/repos/<user|org>/<repo>/zipball/<tag>

However, these archives contain all files found in the projects repository. To exclude repository content (e.g. documentation, .git-files and so one) from being added to these archives, export-ignore can be used as the release feature pays attention to .gitattributes

Therefore, a useful template for .gitattributes would be as useful als it is for .gitignore

Minimum content:

• Which license to choose when? Simple "if this then that" style including reasoning. Maybe referring to https://choosealicense.com/licenses/ including a few comments is just enough.
• How and if: update copyright information. This issue is not tinkered out and might need a lawyer. US-centric, outdated postings on the Internet does not help. We currently assume it simply is not needed to update or put a -2023 into notices like Copyright 2020 foundata GmbH in e.g. an Apache 2.0 LICENSE file, especially in Germany. This should be sorted out for Apache-2.0 and GPL-2.0-or-later first. Maybe(!) helpful:
  • https://www.apache.org/legal/apply-license.html
  • https://www.gnu.org/licenses/gpl-howto.html
  • https://opensource.stackexchange.com/questions/2171/refreshing-shared-copyright-dates-in-apache-2-0-licensed-code
  • https://softwareengineering.stackexchange.com/questions/130478/what-copyright-date-for-an-update-to-an-open-source-project-from-last-year)

Names and URLs should not change. A guide should document our rules and help to prevent wasting too much time on repetitive work.

Note Comments based help, propably in sync with the VSCode extension / formatter:

• https://learn.microsoft.com/en-us/powershell/scripting/developer/help/examples-of-comment-based-help
• PowerShell/vscode-powershell#3926 (comment) (which position to prefer?)

Our current approach to introduce REUSE is

1. .reuse/dep5 with Files: * stanza
2. Use header comment in files with a high profitability to be used stand-alone, e.g. script files
3. The header must state the same license as the default or an explicit entry in .reuse/dep5

The main reasoning for this was (after discussions):

1. Having a compliant default is a good machine readable staring point and far better than simple LICENSE files + README.md entry, especially as preparation for multiple licenses
2. the reuse lint tool complains with a deprecation warning even if the license in .reuse/dep5 and the inline header is exactly the same.

We like the default as it prevents the need to put license information for very few, insignificant files and tooling directories while still making it technically easy to determine the license plus putting license headers in nearly every file in the future.

However, our .reuse/dep5 with Files: * stanza-default seems to be strongly discouraged (see fsfe/reuse-docs#117, especially one comment). We therefore should discuss how to proceed and how to adapt licensing-how-to-apply.md.

Additionally, the Gem used by GitHub and others is still not able to detect the license of our repositories automatically because of this. Symlinks might be the solution (but this is a good example why Files: * is so pleasant... it is clumsy to have a LICENSE file because of licensee-Gem issues even if a LICENSE.license is not needed as REUSE ignores a COPYING or LICENSE file in the root).

Licensee even does not support symlinks (while reuse lint does), so one could only put a LICENSE file in the project root and create a Symlink to it in the LICENSES directory to prevent duplication.

REUSE is using SPDX tags for the inline comments and .license files. It is good to know how they work. A few examples should be added to our guide, especially handling:

• SPDX-FileCopyrightText: Can be used multiple times in a row, cf. https://spdx.github.io/spdx-spec/v2.3/file-tags/#h2-file-tags-format
• SPDX-SPDX-FileContributor: Exists, quite useful if a snippet or file was copied form another project but only changed in a minimal way to fit into another context.
• SPDX-Snippet exists, cf. https://spdx.github.io/spdx-spec/v2.3/file-tags/#h3-snippet-tags-format

  SPDX-License-Identifier: MIT
  SPDX-SnippetCopyrightText: 2022 Jane Doe <[email protected]>
  ...
  SPDX-SnippetEnd
  

cf https://clearlydefined.io/about. This issue is more a reminder for evaluation, we did not know about the project yet.

See Licensing guide: How to apply licenses for more information. We might register the repo at https://api.reuse.software/ afterwards.

We have tons of best practices (beside "don't use a shell script :-D") which should be converted into a public visible guideline document.