From 498830b0630d69973428d69f6b902e725dce5d1c Mon Sep 17 00:00:00 2001 From: Garry O'Donnell Date: Thu, 25 Aug 2022 11:41:35 +0100 Subject: [PATCH 1/6] Recommend remote containers extensio Added the remote containers extension (`ms-vscode-remote.remote-containers`) to the recommended extensions json for VSCode --- .vscode/extensions.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 734f215e..d173f8d6 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -1,7 +1,8 @@ { "recommendations": [ + "ms-vscode-remote.remote-containers" "ms-python.vscode-pylance", "ms-python.python", "ryanluker.vscode-coverage-gutters" ] -} \ No newline at end of file +} From 73ad00d542838a0762ae5dca9a3325125c19f08d Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 22 Aug 2022 16:32:04 +0000 Subject: [PATCH 2/6] Bump actions/setup-python from 2 to 4 Bumps [actions/setup-python](https://github.com/actions/setup-python) from 2 to 4. - [Release notes](https://github.com/actions/setup-python/releases) - [Commits](https://github.com/actions/setup-python/compare/v2...v4) --- updated-dependencies: - dependency-name: actions/setup-python dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] --- .github/workflows/code.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/code.yml b/.github/workflows/code.yml index 97aacad1..af0a3567 100644 --- a/.github/workflows/code.yml +++ b/.github/workflows/code.yml @@ -17,7 +17,7 @@ jobs: - name: Checkout uses: actions/checkout@v2 - - uses: actions/setup-python@v2 + - uses: actions/setup-python@v4 with: python-version: "3.10" @@ -150,7 +150,7 @@ jobs: - name: Checkout uses: actions/checkout@v2 - - uses: actions/setup-python@v2 + - uses: actions/setup-python@v4 with: python-version: "3.10" From 19f137f1d8aeb8c4aec632ad25fa1cabb303a133 Mon Sep 17 00:00:00 2001 From: Giles Knap Date: Thu, 25 Aug 2022 13:52:54 +0000 Subject: [PATCH 3/6] updates from review --- .containerignore | 1 + .devcontainer.json | 3 +-- .gitattributes | 1 - .github/workflows/code.yml | 23 +++++++++------- .../workflows}/container_tests.sh | 0 .github/workflows/linkcheck.yml | 2 +- CONTRIBUTING.rst | 4 +-- Dockerfile | 1 + docs/explanations.rst | 2 +- docs/explanations/decisions.rst | 17 ++++++++++++ .../0001-record-architecture-decisions.rst | 26 +++++++++++++++++++ docs/explanations/why-is-something-so.rst | 7 ----- docs/reference.rst | 2 +- docs/tutorials/installation.rst | 9 ++++++- pyproject.toml | 5 +--- setup.cfg | 2 -- tests/test_boilerplate_removed.py | 6 ----- 17 files changed, 73 insertions(+), 38 deletions(-) delete mode 100644 .gitattributes rename {tests => .github/workflows}/container_tests.sh (100%) create mode 100644 docs/explanations/decisions.rst create mode 100644 docs/explanations/decisions/0001-record-architecture-decisions.rst delete mode 100644 docs/explanations/why-is-something-so.rst diff --git a/.containerignore b/.containerignore index 449757bc..eb7d5ae1 100644 --- a/.containerignore +++ b/.containerignore @@ -4,3 +4,4 @@ dist/ .mypy_cache .tox .venv* +venv* diff --git a/.devcontainer.json b/.devcontainer.json index d1bc3af8..6dce61fe 100644 --- a/.devcontainer.json +++ b/.devcontainer.json @@ -12,7 +12,7 @@ }, // Set *default* container specific settings.json values on container create. "settings": { - "python.defaultInterpreterPath": "/usr/local/bin/python", + "python.defaultInterpreterPath": "/venv/bin/python", "python.linting.enabled": true }, // Add the IDs of extensions you want installed when the container is created. @@ -23,7 +23,6 @@ // Make sure the files we are mapping into the container exist on the host "initializeCommand": "bash -c 'for i in $HOME/.inputrc $HOME/.bashrc_dev; do [ -f $i ] || touch $i; done'", "runArgs": [ - "--privileged", "--net=host", "-v=${localEnv:HOME}/.ssh:/root/.ssh", "-v=${localEnv:HOME}/.bashrc_dev:/root/.bashrc", diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 075748c4..00000000 --- a/.gitattributes +++ /dev/null @@ -1 +0,0 @@ -src/*/_version_git.py export-subst diff --git a/.github/workflows/code.yml b/.github/workflows/code.yml index af0a3567..7a6b33c7 100644 --- a/.github/workflows/code.yml +++ b/.github/workflows/code.yml @@ -5,7 +5,7 @@ on: pull_request: schedule: # Run every Monday at 8am to check latest versions of dependencies - - cron: "0 8 * * MON" + - cron: "0 8 * * WED" jobs: lint: @@ -23,9 +23,9 @@ jobs: - name: Lint run: | - touch requirements_dev.txt + touch requirements_dev.txt requirements.txt python -m pip install --upgrade pip - python -m pip install -r requirements_dev.txt -e .[dev] + python -m pip install -r requirements.txt -r requirements_dev.txt -e .[dev] tox -e pre-commit,mypy test: @@ -59,7 +59,7 @@ jobs: run: pytest tests - name: Upload coverage to Codecov - uses: codecov/codecov-action@v2 + uses: codecov/codecov-action@v3 with: name: ${{ matrix.python }}/${{ matrix.os }} files: cov.xml @@ -82,8 +82,7 @@ jobs: with: path: /tmp/.buildx-cache key: ${{ runner.os }}-buildx-${{ github.sha }} - restore-keys: | - ${{ runner.os }}-buildx- + restore-keys: ${{ runner.os }}-buildx- - name: Log in to GitHub Docker Registry if: github.event_name != 'pull_request' @@ -118,10 +117,17 @@ jobs: - name: Run tests in the container locked with requirements_dev.txt run: | - docker run --name test build bash /project/tests/container_tests.sh + docker run --name test build bash /project/.github/workflows/container_tests.sh docker cp test:/project/dist . docker cp test:/project/requirements.txt . docker cp test:/project/requirements_dev.txt . + docker cp test:/project/cov.xml . + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v3 + with: + name: 3.10-locked/ubuntu-latest + files: cov.xml - name: Build runtime image uses: docker/build-push-action@v3 @@ -147,9 +153,6 @@ jobs: runs-on: ubuntu-latest steps: - - name: Checkout - uses: actions/checkout@v2 - - uses: actions/setup-python@v4 with: python-version: "3.10" diff --git a/tests/container_tests.sh b/.github/workflows/container_tests.sh similarity index 100% rename from tests/container_tests.sh rename to .github/workflows/container_tests.sh diff --git a/.github/workflows/linkcheck.yml b/.github/workflows/linkcheck.yml index 3dc4df42..788db447 100644 --- a/.github/workflows/linkcheck.yml +++ b/.github/workflows/linkcheck.yml @@ -3,7 +3,7 @@ name: Link Check on: schedule: # Run every Monday at 8am to check URL links still resolve - - cron: "0 8 * * MON" + - cron: "0 8 * * WED" jobs: docs: diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0dcaa202..a48c0ceb 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -61,7 +61,7 @@ The code in this repository conforms to standards set by the following tools: - isort_ for import ordering - mypy_ for static type checking -flake8 and black be run by pre-commit_. You can run the above checks on +flake8 and black and isort are run by pre-commit_. You can run the above checks on all files with this command:: $ tox -e pre-commit,mypy @@ -125,7 +125,7 @@ Release Process To make a new release, please follow this checklist: -- Choose a new PEP440 compliant release number +- Choose a new PEP440 compliant release number (see https://peps.python.org/pep-0440/) - Go to the GitHub release_ page - Choose ``Draft New Release`` - Click ``Choose Tag`` and supply the new tag you chose (click create new tag) diff --git a/Dockerfile b/Dockerfile index 57ac6a99..0d993fcf 100644 --- a/Dockerfile +++ b/Dockerfile @@ -31,6 +31,7 @@ RUN cd /project && \ pip install --upgrade pip && \ pip install -r requirements.txt dist/*.whl && \ pip freeze > requirements.txt && \ + # we don't want to include our own wheel in requirements - remove with sed sed -i '/file:\/\//d' requirements.txt FROM python:3.10-slim as runtime diff --git a/docs/explanations.rst b/docs/explanations.rst index 39de4e6b..1e329673 100644 --- a/docs/explanations.rst +++ b/docs/explanations.rst @@ -8,4 +8,4 @@ Explanation of how the library works and why it works that way. .. toctree:: :caption: Explanations - explanations/why-is-something-so + explanations/decisions diff --git a/docs/explanations/decisions.rst b/docs/explanations/decisions.rst new file mode 100644 index 00000000..5841e6ea --- /dev/null +++ b/docs/explanations/decisions.rst @@ -0,0 +1,17 @@ +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, You can obtain one at http://mozilla.org/MPL/2.0/. + +Architectural Decision Records +============================== + +We record major architectural decisions in Architecture Decision Records (ADRs), +as `described by Michael Nygard +`_. +Below is the list of our current ADRs. + +.. toctree:: + :maxdepth: 1 + :glob: + + decisions/* \ No newline at end of file diff --git a/docs/explanations/decisions/0001-record-architecture-decisions.rst b/docs/explanations/decisions/0001-record-architecture-decisions.rst new file mode 100644 index 00000000..b2d3d0fe --- /dev/null +++ b/docs/explanations/decisions/0001-record-architecture-decisions.rst @@ -0,0 +1,26 @@ +1. Record architecture decisions +================================ + +Date: 2022-02-18 + +Status +------ + +Accepted + +Context +------- + +We need to record the architectural decisions made on this project. + +Decision +-------- + +We will use Architecture Decision Records, as `described by Michael Nygard +`_. + +Consequences +------------ + +See Michael Nygard's article, linked above. To create new ADRs we will copy and +paste from existing ones. diff --git a/docs/explanations/why-is-something-so.rst b/docs/explanations/why-is-something-so.rst deleted file mode 100644 index d7a4e218..00000000 --- a/docs/explanations/why-is-something-so.rst +++ /dev/null @@ -1,7 +0,0 @@ -Why is something the way it is -============================== - -Often, reading the code will not explain *why* it is written that way. These -explanations should be grouped together in articles here. They might include -history of python3-pip-skeleton, architectural decisions, or the -real world tests that influenced the design of python3-pip-skeleton. diff --git a/docs/reference.rst b/docs/reference.rst index 956e36b6..bfa7a4f4 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -3,7 +3,7 @@ Reference ========= -Practical step-by-step guides for the more experienced user. +Technical reference material including APIs and release notes. .. toctree:: :caption: Reference diff --git a/docs/tutorials/installation.rst b/docs/tutorials/installation.rst index e1ade2c7..bbffd015 100644 --- a/docs/tutorials/installation.rst +++ b/docs/tutorials/installation.rst @@ -4,7 +4,7 @@ Installation Check your version of python ---------------------------- -You will need python 3.7 or later. You can check your version of python by +You will need python 3.8 or later. You can check your version of python by typing into a terminal:: python3 --version @@ -36,3 +36,10 @@ The library should now be installed and the commandline interface on your path. You can check the version that has been installed by typing:: python3-pip-skeleton --version + +Running in a container +---------------------- + +To pull the container from github container registry and run:: + + docker run ghcr.io/epics-containers/python3-pip-skeleton:main --version diff --git a/pyproject.toml b/pyproject.toml index 1cacf8ab..1bb995d5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,8 +1,5 @@ [build-system] -# To get a reproducible wheel, wheel must be pinned to the same version as in -# dls-python3, and setuptools must produce the same dist-info. Cap setuptools -# to the last version that didn't add License-File to METADATA -requires = ["setuptools<57", "wheel==0.33.1"] +requires = ["setuptools>=45", "setuptools_scm[toml]>=6.2", "wheel"] build-backend = "setuptools.build_meta" [tool.setuptools_scm] diff --git a/setup.cfg b/setup.cfg index e251dac6..36f8418b 100644 --- a/setup.cfg +++ b/setup.cfg @@ -114,8 +114,6 @@ skipinstall=true passenv = PYTHONPATH HOME -setenv = - QT_QPA_PLATFORM = offscreen allowlist_externals = pytest pre-commit diff --git a/tests/test_boilerplate_removed.py b/tests/test_boilerplate_removed.py index 70766e44..506c1e3c 100644 --- a/tests/test_boilerplate_removed.py +++ b/tests/test_boilerplate_removed.py @@ -56,9 +56,3 @@ def test_changed_README_body(): "This is where you should put some images or code snippets", "to include some features and why people should use it", ) - - -def test_explanations_written(): - assert_not_exists( - "docs/explanations/why-is-something-so.rst", "and write some docs/explanations" - ) From cfcc162d970df770cfe0e46611adc7ba98075734 Mon Sep 17 00:00:00 2001 From: Giles Knap Date: Thu, 25 Aug 2022 14:06:37 +0000 Subject: [PATCH 4/6] system python for lint --- .devcontainer.json | 3 +-- .github/workflows/code.yml | 13 ++++--------- pyproject.toml | 2 +- 3 files changed, 6 insertions(+), 12 deletions(-) diff --git a/.devcontainer.json b/.devcontainer.json index 6dce61fe..d0921df6 100644 --- a/.devcontainer.json +++ b/.devcontainer.json @@ -21,11 +21,10 @@ "ms-python.vscode-pylance" ], // Make sure the files we are mapping into the container exist on the host - "initializeCommand": "bash -c 'for i in $HOME/.inputrc $HOME/.bashrc_dev; do [ -f $i ] || touch $i; done'", + "initializeCommand": "bash -c 'for i in $HOME/.inputrc; do [ -f $i ] || touch $i; done'", "runArgs": [ "--net=host", "-v=${localEnv:HOME}/.ssh:/root/.ssh", - "-v=${localEnv:HOME}/.bashrc_dev:/root/.bashrc", "-v=${localEnv:HOME}/.inputrc:/root/.inputrc" ], "mounts": [ diff --git a/.github/workflows/code.yml b/.github/workflows/code.yml index 7a6b33c7..ed3941a1 100644 --- a/.github/workflows/code.yml +++ b/.github/workflows/code.yml @@ -17,15 +17,15 @@ jobs: - name: Checkout uses: actions/checkout@v2 - - uses: actions/setup-python@v4 + - name: Setup python + uses: actions/setup-python@v4 with: python-version: "3.10" - name: Lint run: | touch requirements_dev.txt requirements.txt - python -m pip install --upgrade pip - python -m pip install -r requirements.txt -r requirements_dev.txt -e .[dev] + pip install -r requirements.txt -r requirements_dev.txt -e .[dev] tox -e pre-commit,mypy test: @@ -153,18 +153,13 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/setup-python@v4 - with: - python-version: "3.10" - - uses: actions/download-artifact@v3 - name: Install sdist in a venv and check cli works # ${GITHUB_REPOSITORY##*/} is the repo name without org # Replace this with the cli command if different to the repo name run: | - python -m pip install --upgrade pip - python -m pip install build_files/dist/*.gz + pip install build_files/dist/*.gz ${GITHUB_REPOSITORY##*/} --version release: diff --git a/pyproject.toml b/pyproject.toml index 1bb995d5..1b8c998a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,5 +1,5 @@ [build-system] -requires = ["setuptools>=45", "setuptools_scm[toml]>=6.2", "wheel"] +requires = ["setuptools>=64", "setuptools_scm[toml]>=6.2", "wheel"] build-backend = "setuptools.build_meta" [tool.setuptools_scm] From a3546c77ce4963399012b5fbcb39b88b625cafa6 Mon Sep 17 00:00:00 2001 From: Giles Knap Date: Fri, 26 Aug 2022 07:49:41 +0000 Subject: [PATCH 5/6] better release files --- .github/workflows/code.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/code.yml b/.github/workflows/code.yml index ed3941a1..c853aa0a 100644 --- a/.github/workflows/code.yml +++ b/.github/workflows/code.yml @@ -165,7 +165,7 @@ jobs: release: # upload to PyPI and make a release on every tag if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags') - needs: [lint, container] + needs: container runs-on: ubuntu-latest steps: @@ -177,7 +177,8 @@ jobs: uses: softprops/action-gh-release@1e07f4398721186383de40550babbdf2b84acfc5 # v0.1.14 with: files: | - build_files/* + build_files/requirements* + build_files/dist generate_release_notes: true env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} From 9f2d957c8077741c880baf3af6678d14c5d59551 Mon Sep 17 00:00:00 2001 From: Giles Knap Date: Fri, 26 Aug 2022 08:14:31 +0000 Subject: [PATCH 6/6] final review changes --- .github/workflows/code.yml | 15 ++------------- .github/workflows/docs.yml | 2 +- .github/workflows/linkcheck.yml | 4 ---- .gitignore | 8 +++----- .gitremotes | 1 - .vscode/tasks.json | 4 ++-- README.rst | 2 -- tests/test_boilerplate_removed.py | 13 ++++++++----- .../{test_dls_python3_skeleton.py => test_cli.py} | 0 9 files changed, 16 insertions(+), 33 deletions(-) delete mode 100644 .gitremotes rename tests/{test_dls_python3_skeleton.py => test_cli.py} (100%) diff --git a/.github/workflows/code.yml b/.github/workflows/code.yml index c853aa0a..638acce4 100644 --- a/.github/workflows/code.yml +++ b/.github/workflows/code.yml @@ -77,13 +77,6 @@ jobs: with: fetch-depth: 0 - - name: Cache Docker layers - uses: actions/cache@v3 - with: - path: /tmp/.buildx-cache - key: ${{ runner.os }}-buildx-${{ github.sha }} - restore-keys: ${{ runner.os }}-buildx- - - name: Log in to GitHub Docker Registry if: github.event_name != 'pull_request' uses: docker/login-action@v2 @@ -111,8 +104,6 @@ jobs: tags: build:latest context: . target: build - cache-from: type=local,src=/tmp/.buildx-cache - cache-to: type=local,dest=/tmp/.buildx-cache load: true - name: Run tests in the container locked with requirements_dev.txt @@ -136,8 +127,6 @@ jobs: tags: ${{ steps.meta.outputs.tags }} context: . labels: ${{ steps.meta.outputs.labels }} - cache-from: type=local,src=/tmp/.buildx-cache - cache-to: type=local,dest=/tmp/.buildx-cache - name: Upload build files uses: actions/upload-artifact@v3 @@ -177,8 +166,8 @@ jobs: uses: softprops/action-gh-release@1e07f4398721186383de40550babbdf2b84acfc5 # v0.1.14 with: files: | - build_files/requirements* - build_files/dist + build_files/* + build_files/dist/* generate_release_notes: true env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f81536d0..534395b9 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -44,7 +44,7 @@ jobs: run: tox -e docs - name: Move to versioned directory - # e.g. master or 0.1.2 + # e.g. main or 0.1.2 run: mv build/html ".github/pages/${GITHUB_REF##*/}" - name: Write versions.txt diff --git a/.github/workflows/linkcheck.yml b/.github/workflows/linkcheck.yml index 788db447..60852749 100644 --- a/.github/workflows/linkcheck.yml +++ b/.github/workflows/linkcheck.yml @@ -16,10 +16,6 @@ jobs: runs-on: ubuntu-latest steps: - - name: Avoid git conflicts when tag and branch pushed at same time - if: startsWith(github.ref, 'refs/tags') - run: sleep 60 - - name: Checkout uses: actions/checkout@v2 with: diff --git a/.gitignore b/.gitignore index a8570dee..e0fba46a 100644 --- a/.gitignore +++ b/.gitignore @@ -60,10 +60,8 @@ docs/_build/ # PyBuilder target/ -# DLS build dir and virtual environment -/prefix/ -/venv/ -/lightweight-venv/ -/installed.files +# likely venv names .venv* +venv* + diff --git a/.gitremotes b/.gitremotes deleted file mode 100644 index 96130962..00000000 --- a/.gitremotes +++ /dev/null @@ -1 +0,0 @@ -github git@github.com:epics-containers/python3-pip-skeleton.git diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 0619a51e..946e69d4 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -5,8 +5,8 @@ "tasks": [ { "type": "shell", - "label": "Tests with coverage", - "command": "tox -e pytest", + "label": "Tests, lint and docs", + "command": "tox -p", "options": { "cwd": "${workspaceRoot}" }, diff --git a/README.rst b/README.rst index 669df5f3..360d0ef6 100644 --- a/README.rst +++ b/README.rst @@ -9,8 +9,6 @@ python3-pip-skeleton adopt this skeleton project see https://epics-containers.github.io/python3-pip-skeleton-cli - [Remove this note when adopting skeleton.] - This is where you should write a short paragraph that describes what your module does, how it does it, and why people should use it. diff --git a/tests/test_boilerplate_removed.py b/tests/test_boilerplate_removed.py index 506c1e3c..f5204fa9 100644 --- a/tests/test_boilerplate_removed.py +++ b/tests/test_boilerplate_removed.py @@ -24,11 +24,6 @@ def assert_not_contains_text(path: str, text: str, explanation: str): skeleton_check(text in contents, f"Please change ./{path} {explanation}") -def assert_not_exists(path: str, explanation: str): - exists = (ROOT / path).exists() - skeleton_check(exists, f"Please delete ./{path} {explanation}") - - # setup.cfg def test_module_description(): conf = configparser.ConfigParser() @@ -50,6 +45,14 @@ def test_changed_README_intro(): ) +def test_removed_adopt_skeleton(): + assert_not_contains_text( + "README.rst", + "This project contains template code only", + "remove the note at the start", + ) + + def test_changed_README_body(): assert_not_contains_text( "README.rst", diff --git a/tests/test_dls_python3_skeleton.py b/tests/test_cli.py similarity index 100% rename from tests/test_dls_python3_skeleton.py rename to tests/test_cli.py