diff --git a/.gitignore b/.gitignore index f56d47f2..a6ebb01c 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/Jenkinsfile b/Jenkinsfile new file mode 100644 index 00000000..d1761cea --- /dev/null +++ b/Jenkinsfile @@ -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' + ) + } + } +} diff --git a/README.rst b/README.rst index d124bae9..1d3ff989 100644 --- a/README.rst +++ b/README.rst @@ -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 `_. +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 `_ +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 ----- diff --git a/build-package.sh b/build-package.sh new file mode 100755 index 00000000..a63907d7 --- /dev/null +++ b/build-package.sh @@ -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]}" diff --git a/update-fork.sh b/update-fork.sh new file mode 100755 index 00000000..a004920a --- /dev/null +++ b/update-fork.sh @@ -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."