Merge pull request #2 from stephen-zhao/develop/ou/20220125

Extend Dev Docs, Fix Publish Devops

Author: stephen-zhao

Makefile

@@ -200,11 +200,11 @@ test: $(MARKER_REQUIREMENTS_SYNCED_DEVTIME)
 
 .PHONY: publish
 publish:
-	python3 -m twine upload dist/*
+	$(PY_IN_VENV_EXE) -m twine upload dist/*
 
 .PHONY: publish-test
 publish-test:
-	python3 -m twine upload --repository testpypi dist/*
+	$(PY_IN_VENV_EXE) -m twine upload --repository testpypi dist/*
 
 
 # ==================== Cleaning Up ====================

README.md

@@ -134,8 +134,42 @@ ambiguous.
 
 ## Development
 
-This project has an extensive `Makefile` for development automation.
+This project has an extensive `Makefile` for development automation. To get started quick: after cloning this project, run `make all`. This should create a virtual environment, install all the required dev-time packages, lint, build, and test the project.
 
-After cloning this project, run `make all` to get started.
+### Virtual Environment Setup
 
-This should create a virtual environment and install all the required dev-time packages.
+You only have to run these once. And `make all` covers these steps automatically, but this is here for your reference.
+
+Use `make reinit-venv` to create a new virtual environment from scratch. This will live inside the project's root. All subsequent make commands will automatically invoke python from inside this virtual environment. You may rerun this to completely wipe the virtual environment and start from scratch.
+
+Use `make init-piptools` to bootstrap the virtual environment.
+
+### Dependency Management
+
+To add more runtime dependencies on pypi packages, add them to `requirements.in`. Then use `make install-requirements` to install them.
+
+To add more devtime dependencies (these will not be deemed dependencies in the distributable/built version of the package), add them to any `*.in` file within the `requirements-devtime.d/` directory. Then use `make install-requirements` to install them.
+
+To upgrade the pinned dependencies, run `make upgrade-requirements`. This will re-resolve the requirements to the latest versions, pin the newly resolved versions, and install them.
+
+### Building
+
+`make all` is the one-stop shop for building the project. It will fix auto-fixable linting errors, raise any additional linting errors, build, run unit tests, and produce a coverage report.
+
+To only check lints or fix lints, use `make lint` or `make fix-lint`.
+
+To only build, use `make build`.
+
+To only test, use `make test`.
+
+### Publishing
+
+Use `make publish-test` to publish to the test pypi repository.
+
+Use `make publish` to publish to the prod repository.
+
+### Cleaning
+
+Use `make clean` to remove build artifacts.
+
+Use `make reinit-venv` if you need to completely reset your virtual environment.

requirements-devtime.d/publish.in

@@ -0,0 +1 @@
+twine

requirements-devtime.txt

@@ -2,26 +2,52 @@
 # This file is autogenerated by pip-compile with python 3.8
 # To update, run:
 #
-#    pip-compile --output-file=requirements-devtime.txt requirements-devtime.d/build.in requirements-devtime.d/lint.in requirements-devtime.d/test.in requirements.in
+#    pip-compile --output-file=requirements-devtime.txt requirements-devtime.d/build.in requirements-devtime.d/lint.in requirements-devtime.d/publish.in requirements-devtime.d/test.in requirements.in
 #
 -e file:///mnt/c/Projects/Dev/datetime_matcher
     # via -r requirements-devtime.d/test.in
 attrs==21.4.0
     # via pytest
 black==21.12b0
     # via -r requirements-devtime.d/lint.in
+bleach==4.1.0
+    # via readme-renderer
 build==0.7.0
     # via -r requirements-devtime.d/build.in
+certifi==2021.10.8
+    # via requests
+cffi==1.15.0
+    # via cryptography
+charset-normalizer==2.0.10
+    # via requests
 click==8.0.3
     # via black
+colorama==0.4.4
+    # via twine
 coverage[toml]==6.2
     # via pytest-cov
+cryptography==36.0.1
+    # via secretstorage
+docutils==0.18.1
+    # via readme-renderer
 flake8==4.0.1
     # via -r requirements-devtime.d/lint.in
+idna==3.3
+    # via requests
+importlib-metadata==4.10.1
+    # via
+    #   keyring
+    #   twine
 iniconfig==1.1.1
     # via pytest
 isort==5.10.1
     # via -r requirements-devtime.d/lint.in
+jeepney==0.7.1
+    # via
+    #   keyring
+    #   secretstorage
+keyring==23.5.0
+    # via twine
 mccabe==0.6.1
     # via flake8
 mypy==0.931
@@ -32,12 +58,15 @@ mypy-extensions==0.4.3
     #   mypy
 packaging==21.3
     # via
+    #   bleach
     #   build
     #   pytest
 pathspec==0.9.0
     # via black
 pep517==0.12.0
     # via build
+pkginfo==1.8.2
+    # via twine
 platformdirs==2.4.1
     # via black
 pluggy==1.0.0
@@ -46,8 +75,12 @@ py==1.11.0
     # via pytest
 pycodestyle==2.8.0
     # via flake8
+pycparser==2.21
+    # via cffi
 pyflakes==2.4.0
     # via flake8
+pygments==2.11.2
+    # via readme-renderer
 pyparsing==3.0.7
     # via packaging
 pytest==6.2.5
@@ -56,6 +89,20 @@ pytest==6.2.5
     #   pytest-cov
 pytest-cov==3.0.0
     # via -r requirements-devtime.d/test.in
+readme-renderer==32.0
+    # via twine
+requests==2.27.1
+    # via
+    #   requests-toolbelt
+    #   twine
+requests-toolbelt==0.9.1
+    # via twine
+rfc3986==2.0.0
+    # via twine
+secretstorage==3.3.1
+    # via keyring
+six==1.16.0
+    # via bleach
 toml==0.10.2
     # via pytest
 tomli==1.2.3
@@ -65,7 +112,17 @@ tomli==1.2.3
     #   coverage
     #   mypy
     #   pep517
+tqdm==4.62.3
+    # via twine
+twine==3.7.1
+    # via -r requirements-devtime.d/publish.in
 typing-extensions==4.0.1
     # via
     #   black
     #   mypy
+urllib3==1.26.8
+    # via requests
+webencodings==0.5.1
+    # via bleach
+zipp==3.7.0
+    # via importlib-metadata