Merge pull request #8 from epics-containers/dev

merge skeleton features

Author: gilesknap

.github/workflows/code.yml

@@ -2,21 +2,16 @@ name: Code CI
 
 on:
   push:
-    branches:
-      # Restricting to these branches and tags stops duplicate jobs on internal
-      # PRs but stops CI running on internal branches without a PR. Delete the
-      # next 5 lines to restore the original behaviour
-      - master
-      - main
-    tags:
-      - "*"
   pull_request:
   schedule:
     # Run every Monday at 8am to check latest versions of dependencies
     - cron: "0 8 * * MON"
 
 jobs:
   lint:
+    # pull requests are a duplicate of a branch push if they are from within the
+    # same repo. Skip these
+    if: github.event_name != 'pull_request' || github.event.pull_request.repository == github.repository
     runs-on: "ubuntu-latest"
     steps:
       - name: Checkout
@@ -28,6 +23,7 @@ jobs:
           tox -e pre-commit,mypy
 
   wheel:
+    if: github.event_name != 'pull_request' || github.event.pull_request.repository == github.repository
     strategy:
       fail-fast: false
       matrix:
@@ -59,6 +55,7 @@ jobs:
         run: pipx run --python $(which python${{ matrix.python }}) --spec dist/*.whl python3-pip-skeleton --version
 
   test:
+    if: github.event_name != 'pull_request' || github.event.pull_request.repository == github.repository
     strategy:
       fail-fast: false
       matrix:
@@ -98,17 +95,16 @@ jobs:
       - name: Install with locked dependencies
         if: matrix.lock
         run: |
-          echo '# runtime dependencies' > requirements.txt 
-          echo '# developer dependencies' > requirements_dev.txt
-          # above avoids zero length requirements files
+          touch requirements.txt 
+          touch requirements_dev.txt
           pip install -r requirements.txt -e .
           pip freeze --exclude-editable >> requirements.txt
           pip install -r requirements_dev.txt -e .[dev]
           pip freeze --exclude-editable >> requirements_dev.txt
 
       - name: Install with latest dependencies
         if: ${{ ! matrix.lock }}
-        run: pip install -e .[dev]
+        run: pip install .[dev]
 
       - name: Run tests
         run: pytest tests

.github/workflows/docs.yml

@@ -2,10 +2,6 @@ name: Docs CI
 
 on:
   push:
-    branches:
-      # Add more branches here to publish docs from other branches
-      - master
-      - main
     tags:
       - "*"
   pull_request:

README.rst

@@ -26,22 +26,22 @@ It integrates the following tools:
   - which verifies all the things that CI does
 - If you use VSCode, it will run black, flake8, isort and mypy on save
 
-The the related ``skeleton`` repo skeleton_ for this module contains the source 
+The the related skeleton_ repo for this module contains the source 
 code that can be merged into new or existing projects, and pulled from to 
 keep them up to date. It can also serve as a working example for those who 
 would prefer to cherry-pick.
 
 .. _skeleton: https://github.com/epics-containers/python3-pip-skeleton
 
-This ``cli`` repo contains the
+This ``python3-pip-skeleton-cli`` repo contains the
 docs and a command line tool to ease the adoption of this skeleton into a
 new project like this::
 
-    python3-pip-skeleton new /path/to/be/created
+    python3-pip-skeleton new /path/to/be/created --org my_github_user_or_org
 
 and existing projects::
 
-    python3-pip-skeleton existing /path/to/existing/repo
+    python3-pip-skeleton existing /path/to/existing/repo --org my_github_user_or_org
 
 .. |code_ci| image:: https://github.com/epics-containers/python3-pip-skeleton/workflows/Code%20CI/badge.svg?branch=main
     :target: https://github.com/epics-containers/python3-pip-skeleton/actions?query=workflow%3A%22Code+CI%22

docs/explanations.rst

@@ -11,3 +11,4 @@ Explanation of how the library works and why it works that way.
     explanations/why-use-skeleton
     explanations/why-src
     explanations/why-pre-commit
+    explanations/features

docs/explanations/features.rst

@@ -0,0 +1,34 @@
+Feature Update History
+======================
+
+August 18th 2022
+----------------
+
+.. _CLI: https://epics-containers.github.io/python3-pip-skeleton-cli/
+.. _skeleton: https://epics-containers.github.io/python3-pip-skeleton/
+
+- Project split into 2 repos
+  
+  - this project CLI_ provides this documentation and the code for adopting
+    skeleton
+  - the skeleton_ project provides the template source for adoption 
+  - this avoids the confusion of using two 'main' branches in a single repo
+  - it also allows for separate github settings for the CLI and skeleton as
+    follows:
+
+    - TODO list github branch and PR settings 
+
+- Now allow CI to run on all branches but avoid duplicate CI runs using
+  https://github.com/marketplace/actions/skip-duplicate-actions
+- Now use non-editable pip install for tests that do not use requirements.txt
+
+  - This verifies that the packaging is working  
+
+- the --org option when adopting is now mandatory to avoid accidentally 
+  creating a repo for the default org.
+- moved 'contributing.rst' from reference to how-to meaning that we no
+  longer require a dummy how-to article
+- removed example code hello.py meaning that this does not 
+  have to be deleted after adopting. Also removed related tests.
+- Skeleton README reduced to remove example code and to point at 
+  skeleton-cli for instructions.

docs/how-to.rst

@@ -11,3 +11,4 @@ Practical step-by-step guides for the more experienced user.
     how-to/existing
     how-to/update
     how-to/excalidraw
+    how-to/contributing

docs/reference/contributing.rst docs/how-to/contributing.rstdocs/reference/contributing.rst renamed to docs/how-to/contributing.rst

@@ -8,7 +8,6 @@ Practical step-by-step guides for the more experienced user.
 .. toctree::
     :caption: Reference
 
-    reference/contributing
     Releases <https://github.com/epics-containers/python3-pip-skeleton/releases>
     Index <genindex.html#http://>
 

docs/reference.rst

@@ -4,7 +4,7 @@ Installation
 .. note::
 
     If you want to contribute to the library itself, please follow
-    the `../reference/contributing` instructions.
+    the `../how-to/contributing` instructions.
 
 
 Check your version of python

docs/tutorials/installation.rst

@@ -4,7 +4,7 @@ Creating a new repo from the skeleton
 Once you have followed the `installation` tutorial, you can use the
 commandline tool to make a new repo that inherits the skeleton::
 
-    python3-pip-skeleton new /path/to/be/created
+    python3-pip-skeleton new /path/to/be/created --org my_github_user_or_org
 
 This will:
 
@@ -49,9 +49,6 @@ run this, there will be some failing tests::
     FAILED tests/test_boilerplate_removed.py::test_changed_README_body - AssertionError: Please change ./README.rst to include some features and why people should use it
     FAILED tests/test_boilerplate_removed.py::test_removed_CHANGELOG_note - AssertionError: Please change ./CHANGELOG.rst To remove the note at the top
     FAILED tests/test_boilerplate_removed.py::test_changed_CHANGELOG - AssertionError: Please change ./CHANGELOG.rst To summarize changes to your module as you make them
-    FAILED tests/test_boilerplate_removed.py::test_docs_ref_api_changed - AssertionError: Please change ./docs/reference/api.rst to introduce the API for your module
-    FAILED tests/test_boilerplate_removed.py::test_how_tos_written - AssertionError: Please delete ./docs/how-to/accomplish-a-task.rst and write some docs/how-tos
-    FAILED tests/test_boilerplate_removed.py::test_explanations_written - AssertionError: Please delete ./docs/explanations/why-is-something-so.rst and write some docs/explanations
     ========================================================================== 8 failed, 5 passed in 0.28s ==========================================================================
 
 When you change the template text mentioned in the error, these tests will pass.