Browse Source

Improved structure for the instructions.

dev
Franco Masotti 2 months ago
parent
commit
6c8456fca0
Signed by: frnmst GPG Key ID: 24116ED85666780A
  1. 223
      _pages/software_instructions.md

223
_pages/software_instructions.md

@ -15,22 +15,7 @@ permalink: /software/instructions/
- [Terminology](#terminology)
- [Methods](#methods)
- [Upload (what I have to do)](#upload-what-i-have-to-do)
- [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 (what you have to do)](#download-what-you-have-to-do)
- [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)
<!--TOC-->
@ -60,149 +45,137 @@ You may contact me directly to obtain the public key fingerprint in a different
## Terminology
- `project_dir`: the full path directory of the project
- `project`: the project name
- `project_python_module`: the python module name of the project.
For example: `md-toc` is `md_toc`
- `tag`: the git tag name which is usually [semver](https://semver.org/)ed.
- `tag_raw`: same as `tag` but pad each component of the tag with 6 zeros.
For example: `12.121.5` becomes `000012.000121.000005`
- `signing_key`: the public key file used to sign the archive file
- `has_changelog`: the project has a changelog entry for a specific release. Value must be either `true` or `false`
- `is_on_pypi`: the project is on PyPI. Value must be either `true` or `false`
- `project_version_release_date`: the release date of a software version (tag) in UTC format.
This is the one liner command to get the date:
```shell
python3 -c 'from dateutil import parser as dateutil_parser; from dateutil.tz import UTC; import sys; p = dateutil_parser.parse(sys.argv[1]); u=p.astimezone(UTC); print(u.strftime("%Y-%m-%d"))' "$(git tag -l --format='%(taggerdate)' $(git describe --tags $(git rev-list --tags --max-count=1)))"
```
- `project_version_release_timestamp`: the timestamp of a software version (tag) in UTC format.
This is the one liner command to get the timestamp:
```shell
python3 -c 'from dateutil import parser as dateutil_parser; from dateutil.tz import UTC; import sys; p = dateutil_parser.parse(sys.argv[1]); u=p.astimezone(UTC); print(u.strftime("%Y-%m-%d %T"))' "$(git tag -l --format='%(taggerdate)' $(git describe --tags $(git rev-list --tags --max-count=1)))"
```
- `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
Commands are to be run in the project directory.
| Variable | Description | Command |
|----------|-------------|---------|
| project_dir | the full path directory of the project | `export project_dir="$(pwd)"` |
| project | the project name | `export project="$(basename "$(pwd)")"` |
| project_python_module | the python module name of the project. For example: `md-toc` is `md_toc` | `project_python_module="$(basename "$(pwd)" | tr '-' '_')"` |
| project_version_release_date | the release date of a software version (tag) in UTC format | `project_version_release_date="$(python3 -c 'from dateutil import parser as dateutil_parser; from dateutil.tz import UTC; import sys; p = dateutil_parser.parse(sys.argv[1]); u=p.astimezone(UTC); print(u.strftime("%Y-%m-%d"))' "$(git tag -l --format='%(taggerdate)' $(git describe --tags $(git rev-list --tags --max-count=1)))")"` |
| project_version_release_timestamp | the timestamp of a software version (tag) in UTC format | `project_version_release_timestamp="$(python3 -c 'from dateutil import parser as dateutil_parser; from dateutil.tz import UTC; import sys; p = dateutil_parser.parse(sys.argv[1]); u=p.astimezone(UTC); print(u.strftime("%Y-%m-%d %T"))' "$(git tag -l --format='%(taggerdate)' $(git describe --tags $(git rev-list --tags --max-count=1)))")"` |
| tag | the git tag name which is usually [semver](https://semver.org/)ed | `export tag="$(git describe --tags $(git rev-list --tags --max-count=1))` |
| tag_raw | same as `tag` but pad each component of the tag with 6 zeros. For example: `12.121.5` becomes `000012.000121.000005` | - |
| signing_key | the public key file used to sign the archive file | - |
| has_changelog | the project has a changelog entry for a specific release. Value must be either `true` or `false` | - |
| is_on_pypi | the project is on PyPI. Value must be either `true` or `false` | - |
| 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 I have to do)
What follows are the steps I use to upload the software on this page.
What follows are the steps I use to upload the software page.
#### Get the variables
1. create an archive
Go into the project directory and then:
```shell
cd /tmp
git -C ${project_dir} archive --format=tar.gz --output=/tmp/${project}-${tag}.tar.gz --prefix=${project}-${tag}/ ${tag}
```
export project_dir="$(pwd)"
export project="$(basename "$(pwd)")"
export tag="$(git describe --tags $(git rev-list --tags --max-count=1))
2. sign the archive
#### Create an archive
```shell
gpg --armor --output ${project}-${tag}.tar.gz.sig --detach-sig ${project}-${tag}.tar.gz
```
cd /tmp
git -C ${project_dir} archive --format=tar.gz --output=/tmp/${project}-${tag}.tar.gz --prefix=${project}-${tag}/ ${tag}
3. get the checksums
#### Signing
```shell
sha512sum ${project}-${tag}.tar.gz > ${project}-${tag}.tar.gz.SHA512SUM.txt
sha256sum ${project}-${tag}.tar.gz > ${project}-${tag}.tar.gz.SHA256SUM.txt
```
gpg --armor --output ${project}-${tag}.tar.gz.sig --detach-sig ${project}-${tag}.tar.gz
4. if the project is on PyPI
#### Checksums
```shell
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
```
sha512sum ${project}-${tag}.tar.gz > ${project}-${tag}.tar.gz.SHA512SUM.txt
sha256sum ${project}-${tag}.tar.gz > ${project}-${tag}.tar.gz.SHA256SUM.txt
5. create a new entry in the `_pages/software.md` file
#### Python project on PyPI
```markdown
- [`${tag}`]({{ site.baseurl }}/software/${project}-${tag}/release.html)
```
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
6. create a new release file called `_software/${project}-${tag}/release.md`
and add the following. If it is not a Python project
you must omit the `software_name_python_module` variable:
#### Update the entry
```yaml
---
layout: software_release
enable_markdown: true
title: release
excerpt: none
software_name: ${project}
software_name_python_module: ${project_python_module}
software_version: ${tag}
software_version_raw: ${tag_raw}
release_date: ${project_version_release_date}
is_on_pypi: ${is_on_pypi}
has_changelog: ${has_changelog}
signing_public_key: ${signing_key}
---
```
Create a new entry in the `_pages/software.md` file
7. add a changelog file in `_software/${project}-${tag}/changelog.md`.
Add the `### Added`, `### Removed`, etc... contents if applicable.
```
- [`${tag}`]({{ site.baseurl }}/software/${project}-${tag}/release.html)
```
8. in `./_software/CHANGELOG-${project}.md` update the front matter with the appropriate data:
#### Create a new release file
Create a new file called `_software/${project}-${tag}/release.md` and add the following.
If it's not a Python project you must omit `software_name_python_module`:
```yaml
---
layout: software_release
enable_markdown: true
title: release
excerpt: none
software_name: ${project}
software_name_python_module: ${project_python_module}
software_version: ${tag}
software_version_raw: ${tag_raw}
release_date: ${project_version_release_date}
is_on_pypi: ${is_on_pypi}
has_changelog: ${has_changelog}
signing_public_key: ${signing_key}
---
```
#### Update the changelog
Add a changelog file in `_software/${project}-${tag}/changelog.md`.
Add the `### Added`, `### Removed`, etc... contents if applicable.
In `./_software/CHANGELOG-${project}.md`:
- update the front matter with the appropriate data:
- `updated` and `date` must correspond to `${project_version_release_timestamp}`
- `last_version` must correspond to `${tag}`
#### Update the table of contents
Run this command manually or use pre-commit:
md_toc -p github -l 6 software.md
- `updated` and `date` must correspond to `${project_version_release_timestamp}`
- `last_version` must correspond to `${tag}`
### Download (what you have to do)
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:
1. 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}"
```shell
cd /tmp
wget "${public_key_url}"
gpg --import "${public_key_file}"
```
#### Download the repository
2. download the repository
cd /tmp
wget ${url}/${project}-${tag}.tar.gz.sig
```shell
cd /tmp
wget ${url}/${project}-${tag}.tar.gz.sig
```
#### Check the signature
3. check the signature
wget ${url}/${project}-${tag}.tar.gz
gpg --verify ${project}-${tag}.tar.gz.sig
```shell
wget ${url}/${project}-${tag}.tar.gz
gpg --verify ${project}-${tag}.tar.gz.sig
```
#### Run the checksums
4. run the checksums
sha512sum --check ${project}-${tag}.tar.gz.SHA512SUM.txt
sha256sum --check ${project}-${tag}.tar.gz.SHA256SUM.txt
```shell
sha512sum --check ${project}-${tag}.tar.gz.SHA512SUM.txt
sha256sum --check ${project}-${tag}.tar.gz.SHA256SUM.txt
```
#### Extract
5. extract
tar -xvzf ${project}-${tag}.tar.gz
```shell
tar -xvzf ${project}-${tag}.tar.gz
```
#### Python project on PyPI
6. if its is a 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
```shell
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
```

Loading…
Cancel
Save