blog/_pages/software_instructions.md

layout	title	permalink
page	Software instructions	/software/instructions/

Table of contents

• Table of contents
• Terminology
• Methods
  • Upload
    • Get the variables
    • Create an archive
    • Signing
    • Checksums
    • Python project on PyPI
    • Update the entry
    • Create a new release file
    • Update the changelog
    • Update the table of contents
  • Download
    • Get the public key
    • Download the repository
    • Check the signature
    • Run the checksums
    • Extract
    • Python project on PyPI

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 semvered
• 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