Skip to content

6. Other tools

Jump to bottom
Pierre-Yves Lapersonne edited this page Apr 3, 2024 · 6 revisions

Generate template-based text for email

It can be time-wasting to write always the same emails to people to onboard on GitHub projects or for newcomers. In fact the emails are almost each time the same: share resources, explain some rules. So, a PHP script has been written to produce a text to share using some template and configuration file.

php text-generator.php "_templates/new-GitHub-repository-contributors.fr.template.txt" "_templates/values.ini"

It will iterate on each value defined in the values.ini file (easy to parse in PHP thanks to standard API) and replace each occurence of the variable by its value.

Generate THIRD-PARTY file based on user inputs

Sometimes as open source referent or developer, we need to define file listing third-party components. This type of file must contain, for eeach component, its name, cipyright, license (wih URL pointing to its text) and also the version and the copyright owners. It can be a bit boring to fill each time the text or markdown file, that is the reason why this tool has been defined.

First, ask to the user the components to save tin a CSV file)

python3.8 third-party-prompt.py

Then, give this file to another Python script to build the THIRD-PARTY file

# --file: the path to the CSV file containing the details (given by someone or generated by previous command)
# --delimiter: to define how to split each row fields. Do not forget to escape it if ';'
# --avoid: If a version or a copyright field has "?" as value, ignore this field and add nothing related in the outputs
python3.8 third-party-generator.py --file components.csv.result --delimiter \; --avoid \?

# or with default configuration
python3.8 third-party-generator.py

The CSV file produced by the script third-party-prompt.py or processed by third-party-generator.py must follow the format above:

name;repository;licenseName;copyright;version

Meaning:

  • ";" symbol as delimiter
  • name: the name of the component
  • repository: the hyperlink to the repository to get the sources for the readers
  • licenseName: the name of the license in SPDX short-identifier (cf licenses.py)
  • copyright: the copyright owners
  • version: the verison of the component

For example, with the CSV file bellow

SwiftUI-Flow;https://github.com/tevelee/SwiftUI-Flow;MIT;Copyright (c) 2023 Laszlo Teveli;1.2.0
BottomSheet;https://github.com/lucaszischka/BottomSheet;MIT;Copyright (c) 2021-2022 Lucas Zischka;3.1.1
DeclarationAccessibility;https://github.com/Orange-OpenSource/accessibility-statement-lib-ios;Apache-2.0;Copyright (c) 2021-2023 Orange SA;1.2.0

There is plenty of licenses and also a lot of standards. It can be a pain or time consuming to let the user write the license in use for a component, then find the URL pointing to the license text and write it. In fact, such details are still known so we can let the user choose. The licenses.py file lists main licenses we can meet during audits. Each entry in this dictionary has a license name in SPDX short-identifier format and the URL pointing to the license text. Thus these details will be added in the THIRD-PARTY file.

Apply REUSE formatted headers in source files

Prerequisites

  • Python 3.8
  • reuse

Description

Sometimes as open source referent or developer, we want to have our source files formatted with nice headers. Such headers should apply SPDX format and be compliant with REUSE guidelines. You can also have a look on their nice documentation and their GitHub doc too. Thus the update-sources-ehader.py will apply thanks to reuse-tool a predefined header on sources.

But BEWARE, you MUST check your sources diff and ensure you modified ONLY the files you ARE ALLOWED TO modify and keep external copyrights, your are repsonsible of your own code..

How to use it

# Install requirements
pip install -r requirements.txt

# For help
python3.8 update-sources-header.py --help

# Short version
python3.8 update-sources-header.py -t "path/to/project/to/process" -c "Your Company" -n "Software name" -d "Very short software description"

# Long version
python3.8 update-sources-header.py --target "path/to/project/to/process" --company "Your Company" --name "Software name" --description "Very short software description"

How it works

The script will create a Jinja2 template with a predefined pattern defined within the script. It will before ask the user the license applied to the project. Then the template (in .reuse/templates) folder will be placed in the target destination before the run of reuse-tool. This Jinja2 will then be applied to each source files using the monoline comment symbol of the dedicated programming language.

Given the template bellow:

Software Name: SOFTWARE_NAME
{% for copyright_line in copyright_lines %}
{{ copyright_line }}
{% endfor %}
{% for expression in spdx_expressions %}
SPDX-License-Identifier: {{ expression }}
{% endfor %}

This software is distributed under the LICENSE_NAME,
the text of which is available at LICENSE_URL
or see the "LICENSE.txt" file for more details.

Authors: See CONTRIBUTORS.txt
Software description: SOFTWARE_DESCRIPTION"""

And the following command line:

python3.8 update-sources-header.py --target "path/to/some/Swift/project" -c "Cyberdine Inc." -n "Genisys" -d "Just an entertainement system of course"

The header for Swift files will be:

// Software Name: Genisys
// SPDX-FileCopyrightText: Cyberdine Inc.
// SPDX-License-Identifier: AGPL-3.0-only
//
// This software is distributed under the GNU Affero General Public License version 3,
// the text of which is available at https://opensource.org/license/agpl-v3
// or see the "LICENSE.txt" file for more details.
//
// Authors: See CONTRIBUTORS.txt
// Software description: Just an entertainement system of course

You must have a look on your sources, some files can be processed even if you don't want to.

One step further

You may want to use one of our script to check if sources contain headers, see this section in the wiki.

You can also use REUSE to have a linter scanning your project:

reuse lint
Clone this wiki locally