Automate fork rebasing, packaging, and publication

This commit is contained in:
Dandaedre 2026-10-03 15:51:06 +02:00
parent 7b9e9128fe
commit 39a399c2c6
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
5 changed files with 403 additions and 0 deletions

5
.gitignore vendored
View File

@ -18,6 +18,11 @@ release_notes.txt
# IDE files
.idea/
.vscode/
.venv/
.uv-cache/
.uv-python/
.ci-*/
.package-build/
# Ignore external repos used for tests
tests/external_repos/repos

172
Jenkinsfile vendored Normal file
View File

@ -0,0 +1,172 @@
// Add the Gitea webhook configured for this Jenkins installation.
pipeline {
agent { label 'rust_no_docker' }
options {
disableConcurrentBuilds()
skipDefaultCheckout(true)
}
environment {
PYTHONUNBUFFERED = '1'
UV_CACHE_DIR = "${WORKSPACE}/.uv-cache"
UV_PYTHON_INSTALL_DIR = "${WORKSPACE}/.uv-python"
}
stages {
stage('Checkout') {
steps {
deleteDir()
checkout scm
sh 'git fetch --force --tags origin'
}
}
stage('Set up development environment') {
steps {
sh '''
set -eu
command -v uv >/dev/null 2>&1 || {
echo "ERROR: uv is required on the Jenkins worker." >&2
exit 1
}
uv --version
command -v python3
python3 --version
uv venv --python python3 .venv
uv pip install --python .venv/bin/python -e '.[tests,dev]'
'''
}
}
stage('Style') {
steps {
sh 'uv run --no-sync pre-commit run --all-files'
}
}
stage('Tests') {
steps {
sh 'uv run --no-sync python -m unittest'
}
}
stage('Build package') {
steps {
sh './build-package.sh'
}
}
stage('Wheel install with pip') {
steps {
sh '''
set -eu
wheel="$(find dist -maxdepth 1 -type f -name 'vsg-*.whl' -print -quit)"
test -n "${wheel}" || {
echo "ERROR: built wheel was not found." >&2
exit 1
}
python3 -m venv .ci-pip-venv
.ci-pip-venv/bin/python -m pip install "${wheel}"
output="$(
printf 'entity smoke is\nend entity smoke;\n' |
.ci-pip-venv/bin/vsg --stdin --stdout --fix --style jcl --no-failure
)"
printf '%s\n' "${output}" | grep -F 'entity SMOKE is'
'''
}
}
stage('Wheel install with uv') {
steps {
sh '''
set -eu
wheel="$(find dist -maxdepth 1 -type f -name 'vsg-*.whl' -print -quit)"
test -n "${wheel}" || {
echo "ERROR: built wheel was not found." >&2
exit 1
}
uv venv --python .venv/bin/python .ci-uv-venv
uv pip install --python .ci-uv-venv/bin/python "${wheel}"
output="$(
printf 'entity smoke is\nend entity smoke;\n' |
.ci-uv-venv/bin/vsg --stdin --stdout --fix --style jcl --no-failure
)"
printf '%s\n' "${output}" | grep -F 'entity SMOKE is'
'''
}
}
stage('Archive package') {
steps {
archiveArtifacts artifacts: 'dist/*', fingerprint: true, onlyIfSuccessful: true
}
}
stage('Publish package') {
when {
branch 'master'
}
steps {
withCredentials([
string(
credentialsId: 'vsg-gitea-package-token',
variable: 'GITEA_TOKEN'
)
]) {
sh '''
set +x
set -eu
test -n "${GITEA_TOKEN}" || {
echo "ERROR: Jenkins supplied an empty Gitea package token." >&2
exit 1
}
for artifact in dist/vsg-*.tar.gz dist/vsg-*.whl; do
test -f "${artifact}" || {
echo "ERROR: expected package artifact was not found: ${artifact}" >&2
exit 1
}
done
UV_PUBLISH_USERNAME='Dandaedre' \
UV_PUBLISH_PASSWORD="${GITEA_TOKEN}" \
uv publish \
--publish-url 'https://proxy.dandaedre.com/gitea/api/packages/MadGobblins/pypi' \
--check-url 'https://proxy.dandaedre.com/gitea/api/packages/MadGobblins/pypi/simple/' \
--no-attestations \
dist/vsg-*.tar.gz \
dist/vsg-*.whl
'''
}
}
}
}
post {
success {
publishChecks(
conclusion: 'SUCCESS',
name: 'VSG fork CI',
summary: 'VSG tests and package installation checks passed.',
text: 'The wheel was tested through both pip and uv, including stdin/stdout formatting.',
title: 'Build Successful'
)
}
failure {
publishChecks(
conclusion: 'FAILURE',
name: 'VSG fork CI',
summary: 'A VSG fork check failed.',
text: 'Review the Jenkins log for style, tests, build, installation, or publishing failures.',
title: 'Build Failed'
)
}
}
}

View File

@ -148,6 +148,45 @@ Build locally, artifacts will appear in ``dist`` directory.
tox
Fork for ``vsg_bridge_ls``
~~~~~~~~~~~~~~~~~~~~~~~~~
This fork adds ``--stdout`` and ``--no-failure`` so VSG can format editor
buffers through standard streams. It is the VSG backend required for formatting
with `vsg_bridge_ls <https://proxy.dandaedre.com/gitea/MadGobblins/vsg-bridge-ls>`_.
The bridge README is the main user guide for installing both projects and
configuring an editor.
The preferred installation uses uv and the prebuilt Gitea package:
.. code-block:: bash
uv venv .venv
uv pip install --python .venv/bin/python \
--index https://proxy.dandaedre.com/gitea/api/packages/MadGobblins/pypi/simple/ \
vsg
Installing from ``master`` also works with uv, and either source works with
standard pip. See the bridge's
`installation guide <https://proxy.dandaedre.com/gitea/MadGobblins/vsg-bridge-ls/src/branch/main/doc/installation.md>`_
for all supported commands and environment setup.
Fork maintainers can build locally with ``./build-package.sh`` and publish the
new artifacts with:
.. code-block:: bash
./build-package.sh ../gitea_token.txt --publish
On ``master``, Jenkins fetches the Git tags used by
``setuptools-git-versioning``, runs both installation smoke tests, archives the
generated distributions, and publishes those exact artifacts to Gitea. The
required Jenkins credential is documented in the bridge development guide.
Use ``./update-fork.sh`` to fetch upstream tags and rebase the small fork patch
series onto the latest upstream ``master``. The script requires a clean
worktree and automatically aborts a failed rebase.
Usage
-----

135
build-package.sh Executable file
View File

@ -0,0 +1,135 @@
#!/usr/bin/env bash
set -Eeuo pipefail
show_help() {
cat <<'EOF'
Usage: ./build-package.sh [TOKEN_FILE] [--publish]
Build the VSG source distribution and wheel. With --publish, upload the newly
built artifacts to Gitea. TOKEN_FILE overrides all other token sources.
Optional publishing settings:
GITEA_TOKEN token value used when TOKEN_FILE is omitted
GITEA_TOKEN_FILE
token file used when TOKEN_FILE and GITEA_TOKEN are omitted
(default: ../gitea_token.txt)
GITEA_USERNAME Gitea login name (default: Dandaedre)
GITEA_OWNER package owner (default: MadGobblins)
GITEA_URL Gitea base URL (default: https://proxy.dandaedre.com/gitea)
EOF
}
fail_usage() {
echo "ERROR: $1" >&2
show_help >&2
exit 2
}
publish=false
token_file_argument=""
while [ "$#" -gt 0 ]; do
case "$1" in
--publish)
[ "${publish}" = false ] || fail_usage "--publish was specified more than once."
publish=true
;;
-h|--help)
show_help
exit 0
;;
-*)
fail_usage "unknown option: $1"
;;
*)
[ -z "${token_file_argument}" ] || fail_usage "more than one token file was specified."
token_file_argument="$1"
;;
esac
shift
done
if [ -n "${token_file_argument}" ] && [ "${publish}" = false ]; then
fail_usage "TOKEN_FILE requires --publish."
fi
repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || {
echo "ERROR: build-package.sh must run inside a Git worktree." >&2
exit 1
}
gitea_token="${GITEA_TOKEN:-}"
if [ -n "${token_file_argument}" ]; then
gitea_token=""
gitea_token_file="${token_file_argument}"
else
gitea_token_file="${GITEA_TOKEN_FILE:-${repo_root}/../gitea_token.txt}"
fi
if [ "${publish}" = true ] && [ -z "${gitea_token}" ]; then
if [ ! -f "${gitea_token_file}" ] || [ ! -r "${gitea_token_file}" ]; then
fail_usage "token file is not a readable regular file: ${gitea_token_file}"
fi
IFS= read -r gitea_token <"${gitea_token_file}" || :
fi
if [ "${publish}" = true ] && [ -z "${gitea_token}" ]; then
fail_usage "token file is empty: ${gitea_token_file}"
fi
cd "${repo_root}"
if ! command -v uv >/dev/null 2>&1; then
echo "ERROR: uv is required to build the package." >&2
exit 1
fi
if [ ! -x .venv/bin/python ]; then
echo "Creating the required local virtual environment..."
uv venv .venv
fi
readonly build_dir=".package-build"
if [ -e "${build_dir}" ]; then
rm -rf -- "${build_dir}"
fi
echo "Building the source distribution and wheel..."
uv build --no-sources --out-dir "${build_dir}"
shopt -s nullglob
artifacts=("${build_dir}"/vsg-*.tar.gz "${build_dir}"/vsg-*.whl)
if [ "${#artifacts[@]}" -lt 2 ]; then
echo "ERROR: uv build completed without producing both expected package formats." >&2
exit 1
fi
mkdir -p dist
built_artifacts=()
for artifact in "${artifacts[@]}"; do
destination="dist/${artifact##*/}"
cp -- "${artifact}" "${destination}"
built_artifacts+=("${destination}")
done
rm -rf -- "${build_dir}"
echo "Built package artifacts:"
printf ' %s\n' "${built_artifacts[@]}"
if [ "${publish}" = true ]; then
readonly gitea_username="${GITEA_USERNAME:-Dandaedre}"
readonly gitea_owner="${GITEA_OWNER:-MadGobblins}"
readonly gitea_url="${GITEA_URL:-https://proxy.dandaedre.com/gitea}"
echo
echo "Publishing package artifacts to Gitea..."
UV_PUBLISH_USERNAME="${gitea_username}" \
UV_PUBLISH_PASSWORD="${gitea_token}" \
uv publish \
--publish-url "${gitea_url}/api/packages/${gitea_owner}/pypi" \
--check-url "${gitea_url}/api/packages/${gitea_owner}/pypi/simple/" \
--no-attestations \
"${built_artifacts[@]}"
echo "Published package artifacts successfully."
fi
echo
echo "Install the wheel into a uv environment with:"
printf ' uv pip install %q\n' "${built_artifacts[-1]}"

52
update-fork.sh Executable file
View File

@ -0,0 +1,52 @@
#!/usr/bin/env bash
set -Eeuo pipefail
readonly upstream_url="${1:-https://github.com/jeremiah-c-leary/vhdl-style-guide.git}"
readonly upstream_branch="${2:-master}"
readonly upstream_ref="refs/remotes/upstream/${upstream_branch}"
repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || {
echo "ERROR: update-fork.sh must run inside a Git worktree." >&2
exit 1
}
cd "${repo_root}"
if [ -n "$(git status --porcelain)" ]; then
echo "ERROR: refusing to rebase a dirty worktree." >&2
git status --short >&2
exit 1
fi
if [ -z "$(git symbolic-ref --quiet --short HEAD)" ]; then
echo "ERROR: refusing to rebase a detached HEAD." >&2
exit 1
fi
abort_rebase() {
exit_status=$?
trap - EXIT HUP INT TERM
if git rev-parse --verify --quiet REBASE_HEAD >/dev/null; then
echo "ERROR: upstream rebase failed; aborting it now." >&2
if ! git rebase --abort; then
echo "FATAL: git rebase --abort also failed; manual recovery is required." >&2
exit 2
fi
else
echo "ERROR: fork update failed before a rebase was started." >&2
fi
exit "${exit_status}"
}
trap abort_rebase EXIT HUP INT TERM
echo "Fetching ${upstream_branch} and release tags from ${upstream_url}..."
git fetch --tags "${upstream_url}" "${upstream_branch}:${upstream_ref}"
upstream_commit="$(git rev-parse "${upstream_ref}")"
echo "Rebasing fork commits onto ${upstream_commit}..."
git rebase "${upstream_commit}"
trap - EXIT HUP INT TERM
echo "Fork update completed successfully."