---

[INSERT YOUR LOGO IMAGE HERE (IF APPLICABLE)]

[INSERT YOUR REPO / PROJ NAME HERE]

[INSERT A SINGLE SENTENCE DESCRIBING THE PURPOSE OF YOUR REPO / PROJ]

[INSERT YOUR BADGES HERE (SEE: https://shields.io)]

[INSERT SCREENSHOT OF YOUR SOFTWARE, IF APPLICABLE]

[INSERT MORE DETAILED DESCRIPTION OF YOUR REPOSITORY HERE]

[INSERT LIST OF IMPORTANT PROJECT / REPO LINKS HERE]

Features

• [INSERT LIST OF FEATURES IMPORTANT TO YOUR USERS HERE]
• Python build tooling based on PEP-517 and PEP-518 standards
• Build, release and publish automation takes place automatically using GitHub Actions.

Contents

• Quick Start
• Changelog
• FAQ
• Contributing Guide
• License
• Support

Quick Start

This guide provides a quick way to get started with our project. Please see our [docs]([INSERT LINK TO DOCS SITE / WIKI HERE]) for a more comprehensive overview.

Requirements

1. [INSERT LIST OF REQUIREMENTS HERE]

Build System Requirements

Certain properties and permission settings are necessary in GitHub for builds to run automatically. On local development systems builds may be tested in similar fashion with proper tooling installed.

Required repository settings

1. Shared PyPi API Token installed in GitHub Repository Secrets named PYPI_API_TOKEN.
2. Permissions to execute GitHub Actions and perform software tag and release.

Required local tooling

1. Build tooling modules

pip3 install --upgrade build setuptools_scm twine wheel

2. Product required modules (requirements.txt)

pip3 --exists-action w install -r requirements.txt

Setup Instructions

1. [INSERT STEP-BY-STEP SETUP INSTRUCTIONS HERE, WITH OPTIONAL SCREENSHOTS]

Run Instructions

1. [INSERT STEP-BY-STEP RUN INSTRUCTIONS HERE, WITH OPTIONAL SCREENSHOTS]

Usage Examples

• [INSERT LIST OF COMMON USAGE EXAMPLES HERE, WITH OPTIONAL SCREENSHOTS]

Build Instructions

A GitHub Action configuration specifies the series of commands to release and publish the product. Commands are staged and carried out automatically when a tagged release is published to the main branch.

Automated Build Kickoff

1. Edit the [INSERT YOUR PACKAGE NAME]/version.py file with the next release version using the web UI on GitHub main branch.
2. Perform a release using the web UI on GitHub main branch
3. Build, packaging and release to PyPi will execute automatically using GitHub Actions Workflows

Manual Build

These instructions must be entered from the local directory checked out from source control.

1. Manually update [INSERT YOUR PACKAGE NAME]/version.py with the next release version, commit and push to the main branch:

git add [INSERT YOUR PACKAGE NAME]/version.py && git commit -m "Issue #<issue_number>: Updated version for release." && git push

2. Tag using the Git command line:

git tag -a -m "Issue #<issue_number>: Release version <version>" <version>

Note: The <version> must match that in the [INSERT YOUR PACKAGE NAME]/version.py file. 3. Package the product:

• Package an sdist and a tarball: (traditional)

git checkout [INSERT YOUR PACKAGE NAME]/version.py && python3 -m build --wheel

• ... or package an sdist and a zip ...

python3 -m build --wheel && python3 setup.py sdist --format=zip

4. Publish product to PyPi for public distribution by using Twine:

twine check dist/* && twine upload --verbose

... or as a ZIP ...

twine check dist/* && twine upload --verbose dist/*.whl dist/*.zip

Test Instructions (if applicable)

1. [INSERT STEP-BY-STEP TEST INSTRUCTIONS HERE, WITH OPTIONAL SCREENSHOTS]

Local Build Testing

These instructions must be entered from the local directory checked out from source control. A simplified build and release workflow is available for testing locally. Publishing directly to PyPi is not recommended as PyPi permits one upload per release version.

1. Clean application:

rm -r build dist __pycache__ *.egg* .egg* ; git checkout [INSERT YOUR PACKAGE NAME]/version.py ; pip3 uninstall [INSERT YOUR PACKAGE NAME] -y

2. Build and install release locally:

python3 -m build --wheel && python3 setup.py sdist --format=zip
pip3 install [INSERT YOUR PACKAGE NAME] --no-index --find-links file://${PWD}/dist/

... alternately, install an editable build using Pip tooling ...

pip install -e

3. Testing publication to Test PyPi
   Twine will prompt for your Test PyPi username and password.

twine check dist/*
twine upload --repository testpypi --verbose dist/*

Changelog

See our CHANGELOG.md for a history of our changes.

See our [releases page]([INSERT LINK TO YOUR RELEASES PAGE]) for our key versioned releases.

Frequently Asked Questions (FAQ)

[INSERT LINK TO FAQ PAGE OR PROVIDE FAQ INLINE HERE]

Contributing

Interested in contributing to our project? Please see our: CONTRIBUTING.md

For guidance on how to interact with our team, please see our code of conduct located at: CODE_OF_CONDUCT.md

For guidance on our governance approach, including decision-making process and our various roles, please see our governance model at: GOVERNANCE.md

License

See our: LICENSE

Support

[INSERT CONTACT INFORMATION OR PROFILE LINKS TO MAINTAINERS AMONG COMMITTER LIST]