From b5c0adcc4b1a96572968dd58793101c6226ddb97 Mon Sep 17 00:00:00 2001 From: Franco Masotti Date: Mon, 2 Aug 2021 12:16:39 +0200 Subject: [PATCH] Moved instructions to a different page. --- _pages/software.md | 144 ++---------------------------- _pages/software_instructions.md | 152 ++++++++++++++++++++++++++++++++ 2 files changed, 157 insertions(+), 139 deletions(-) create mode 100644 _pages/software_instructions.md diff --git a/_pages/software.md b/_pages/software.md index a40eca5..38e0d56 100644 --- a/_pages/software.md +++ b/_pages/software.md @@ -11,26 +11,8 @@ permalink: /software/ - [Table of contents](#table-of-contents) - [Introduction](#introduction) - [Extract](#extract) -- [Terminology](#terminology) -- [Methods](#methods) - - [Upload](#upload) - - [Get the variables](#get-the-variables) - - [Create an archive](#create-an-archive) - - [Signing](#signing) - - [Checksums](#checksums) - - [Python project on PyPI](#python-project-on-pypi) - - [Update the entry](#update-the-entry) - - [Create a new release file](#create-a-new-release-file) - - [Update the changelog](#update-the-changelog) - - [Update the table of contents](#update-the-table-of-contents) - - [Download](#download) - - [Get the public key](#get-the-public-key) - - [Download the repository](#download-the-repository) - - [Check the signature](#check-the-signature) - - [Run the checksums](#run-the-checksums) - - [Extract](#extract-1) - - [Python project on PyPI](#python-project-on-pypi-1) - [Signing keys](#signing-keys) +- [Instructions](#instructions) - [Software](#software) - [automated-tasks](#automated-tasks) - [Repository](#repository) @@ -95,132 +77,16 @@ The following extract is from a [post by Mike Gerwitz](https://mikegerwitz.com/2 Copyright © 2019 Mike Gerwitz. Licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. -## Terminology - -- `project_dir`: the full path directory of the project -- `project`: the project name -- `project_python_module`: the python module name of the project (e.g: md-toc is md_toc) -- `tag`: the git tag name which is usually [semver](https://semver.org/)ed -- `signing_key`: the public key file used to sign the archive file -- `changelog_slugified_header`: the slugified header corresponding to a tag in a changelog file -- `url`: a generic url -- `PyPI_download_page`: the URL of the download page of the package on PyPI - -## Methods - -### Upload - -What follows are the steps I use to upload the software on this page. - -#### Get the variables - -Go into the project directory and then: - - export project_dir="$(pwd)" - export project="$(basename "$(pwd)")" - export tag="$(git tag | sort --human-numeric-sort --ignore-leading-blanks | tail --lines=1)" - -#### Create an archive - - cd /tmp - git -C ${project_dir} archive --format=tar.gz --output=/tmp/${project}-${tag}.tar.gz --prefix=${project}-${tag}/ ${tag} - -#### Signing - - gpg --armor --output ${project}-${tag}.tar.gz.sig --detach-sig ${project}-${tag}.tar.gz - -#### Checksums - - sha512sum ${project}-${tag}.tar.gz > ${project}-${tag}.tar.gz.SHA512SUM.txt - sha256sum ${project}-${tag}.tar.gz > ${project}-${tag}.tar.gz.SHA256SUM.txt - -#### Python project on PyPI - - make dist - cd dist - sha256sum ${project_python_module}-${tag}-py3-none-any.whl > ${project_python_module}-${tag}-py3-none-any.whl.SHA256SUM.txt - md5sum ${project_python_module}-${tag}-py3-none-any.whl > ${project_python_module}-${tag}-py3-none-any.whl.MD5SUM.txt - -#### Update the entry - -Create a new entry in this file - -``` -- [`${tag}`]({{ site.baseurl }}/software/${project}-${tag}/release.html) -``` - -#### Create a new release file - -Create a new file called `${project}-${tag}/release.md` and add the following: - -``` ---- -layout: default -title: release -excerpt: none ---- - -# ${project}-${tag} - -- [CHANGELOG]({{ site.baseurl }}/software/CHANGELOG-${project}.html#${changelog_slugified_header}) -- [${project}-${tag}.tar.gz]({{ site.baseurl }}/software/${project}-${tag}.tar.gz) -- [SHA512SUM.txt]({{ site.baseurl }}/software/${project}-${tag}.tar.gz.SHA512SUM.txt) -- [SHA256SUM.txt]({{ site.baseurl }}/software/${project}-${tag}.tar.gz.SHA256SUM.txt) -- [signature]({{ site.baseurl }}/software/${project}-${tag}.tar.gz.sig) -- [signing key]({{ site.baseurl }}/pubkeys/${signing_key}) -``` - -#### Update the changelog - -Update the changelog file at `CHANGELOG-${project}.md` - -#### Update the table of contents - - md_toc -p github -l 6 software.md - -### Download - -Run the following to download and verify the software. - -#### Get the public key - -If the public key is unknown you must import it from a trusted source: - - cd /tmp - wget "${public_key_url}" - gpg --import "${public_key_file}" - -#### Download the repository - - cd /tmp - wget ${url}/${project}-${tag}.tar.gz.sig - -#### Check the signature - - wget ${url}/${project}-${tag}.tar.gz - gpg --verify ${project}-${tag}.tar.gz.sig - -#### Run the checksums - - sha512sum --check ${project}-${tag}.tar.gz.SHA512SUM.txt - sha256sum --check ${project}-${tag}.tar.gz.SHA256SUM.txt - -#### Extract - - tar -xvzf ${project}-${tag}.tar.gz - -#### Python project on PyPI - - wget ${PyPI_download_page}/${project_python_module}-${tag}-py3-none-any.whl - sha256sum --check ${project_python_module}-${tag}-py3-none-any.whl.SHA256SUM.txt - md5sum --check ${project_python_module}-${tag}-py3-none-any.whl.MD5SUM.txt - ## Signing keys | Key | Fingerprint | |-----|-------------| | [pgp_pubkey_since_2019.txt]({{ site.baseurl }}/pubkeys/pgp_pubkey_since_2019.txt) | [pgp_pubkey_fingerprint_since_2019.txt]({{ site.baseurl }}/pubkeys/pgp_pubkey_fingerprint_since_2019.txt) | +## Instructions + +[instructions]({{ site.baseurl }}/software/instructions) + ## Software ### automated-tasks diff --git a/_pages/software_instructions.md b/_pages/software_instructions.md new file mode 100644 index 0000000..514d844 --- /dev/null +++ b/_pages/software_instructions.md @@ -0,0 +1,152 @@ +--- +layout: page +title: Software instructions +permalink: /software/instructions/ +--- + +## Table of contents + + + +- [Table of contents](#table-of-contents) +- [Terminology](#terminology) +- [Methods](#methods) + - [Upload](#upload) + - [Get the variables](#get-the-variables) + - [Create an archive](#create-an-archive) + - [Signing](#signing) + - [Checksums](#checksums) + - [Python project on PyPI](#python-project-on-pypi) + - [Update the entry](#update-the-entry) + - [Create a new release file](#create-a-new-release-file) + - [Update the changelog](#update-the-changelog) + - [Update the table of contents](#update-the-table-of-contents) + - [Download](#download) + - [Get the public key](#get-the-public-key) + - [Download the repository](#download-the-repository) + - [Check the signature](#check-the-signature) + - [Run the checksums](#run-the-checksums) + - [Extract](#extract) + - [Python project on PyPI](#python-project-on-pypi-1) + + + +## Terminology + +- `project_dir`: the full path directory of the project +- `project`: the project name +- `project_python_module`: the python module name of the project (e.g: md-toc is md_toc) +- `tag`: the git tag name which is usually [semver](https://semver.org/)ed +- `signing_key`: the public key file used to sign the archive file +- `changelog_slugified_header`: the slugified header corresponding to a tag in a changelog file +- `url`: a generic url +- `PyPI_download_page`: the URL of the download page of the package on PyPI + +## Methods + +### Upload + +What follows are the steps I use to upload the software on this page. + +#### Get the variables + +Go into the project directory and then: + + export project_dir="$(pwd)" + export project="$(basename "$(pwd)")" + export tag="$(git tag | sort --human-numeric-sort --ignore-leading-blanks | tail --lines=1)" + +#### Create an archive + + cd /tmp + git -C ${project_dir} archive --format=tar.gz --output=/tmp/${project}-${tag}.tar.gz --prefix=${project}-${tag}/ ${tag} + +#### Signing + + gpg --armor --output ${project}-${tag}.tar.gz.sig --detach-sig ${project}-${tag}.tar.gz + +#### Checksums + + sha512sum ${project}-${tag}.tar.gz > ${project}-${tag}.tar.gz.SHA512SUM.txt + sha256sum ${project}-${tag}.tar.gz > ${project}-${tag}.tar.gz.SHA256SUM.txt + +#### Python project on PyPI + + make dist + cd dist + sha256sum ${project_python_module}-${tag}-py3-none-any.whl > ${project_python_module}-${tag}-py3-none-any.whl.SHA256SUM.txt + md5sum ${project_python_module}-${tag}-py3-none-any.whl > ${project_python_module}-${tag}-py3-none-any.whl.MD5SUM.txt + +#### Update the entry + +Create a new entry in this file + +``` +- [`${tag}`]({{ site.baseurl }}/software/${project}-${tag}/release.html) +``` + +#### Create a new release file + +Create a new file called `${project}-${tag}/release.md` and add the following: + +``` +--- +layout: default +title: release +excerpt: none +--- + +# ${project}-${tag} + +- [CHANGELOG]({{ site.baseurl }}/software/CHANGELOG-${project}.html#${changelog_slugified_header}) +- [${project}-${tag}.tar.gz]({{ site.baseurl }}/software/${project}-${tag}.tar.gz) +- [SHA512SUM.txt]({{ site.baseurl }}/software/${project}-${tag}.tar.gz.SHA512SUM.txt) +- [SHA256SUM.txt]({{ site.baseurl }}/software/${project}-${tag}.tar.gz.SHA256SUM.txt) +- [signature]({{ site.baseurl }}/software/${project}-${tag}.tar.gz.sig) +- [signing key]({{ site.baseurl }}/pubkeys/${signing_key}) +``` + +#### Update the changelog + +Update the changelog file at `CHANGELOG-${project}.md` + +#### Update the table of contents + + md_toc -p github -l 6 software.md + +### Download + +Run the following to download and verify the software. + +#### Get the public key + +If the public key is unknown you must import it from a trusted source: + + cd /tmp + wget "${public_key_url}" + gpg --import "${public_key_file}" + +#### Download the repository + + cd /tmp + wget ${url}/${project}-${tag}.tar.gz.sig + +#### Check the signature + + wget ${url}/${project}-${tag}.tar.gz + gpg --verify ${project}-${tag}.tar.gz.sig + +#### Run the checksums + + sha512sum --check ${project}-${tag}.tar.gz.SHA512SUM.txt + sha256sum --check ${project}-${tag}.tar.gz.SHA256SUM.txt + +#### Extract + + tar -xvzf ${project}-${tag}.tar.gz + +#### Python project on PyPI + + wget ${PyPI_download_page}/${project_python_module}-${tag}-py3-none-any.whl + sha256sum --check ${project_python_module}-${tag}-py3-none-any.whl.SHA256SUM.txt + md5sum --check ${project_python_module}-${tag}-py3-none-any.whl.MD5SUM.txt