Merge pull request #23 from lincc-frameworks/issue/9/cleanup-readme

Overhaul of the README file

Author: drewoldag

.pre-commit-config.yaml

@@ -32,16 +32,29 @@ repos:
 
     # verify that pyproject.toml is well formed
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: main
+    rev: v0.12.1
     hooks:
       - id: validate-pyproject
         name: Validate syntax of pyproject.toml
         description: Verify that pyproject.toml adheres to the established schema.
 
     # Automatically sort the imports used in .py files
-    - repo: https://github.com/pycqa/isort
-      rev: 5.12.0
-      hooks:
-        - id: isort
-          name: isort (python)
-          description: Sort and organize imports in .py files.
+  - repo: https://github.com/pycqa/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+        name: isort (python)
+        description: Sort and organize imports in .py files.
+
+  - repo: local
+    hooks:
+      - id: pylint
+        name: pylint
+        entry: pylint
+        language: system
+        types: [python]
+        args:
+          [
+            "-rn", # Only display messages
+            "-sn", # Don't display the score
+          ]

README.md

@@ -2,67 +2,150 @@
 
 ## What is this?
 
-This template codifies LINCC-Framework's best practices for python code organization, testing, documentation, and automation.
+This project template codifies LINCC-Framework's best practices for python code organization, testing, documentation, and automation. It is meant to help new python projects get started quickly, letting the user focus on writing code. The template takes care of the minutia of directory structures, tool configurations, and automated testing until the user is ready to take over.
 
-## How to use this Copier template:
+[Copier](https://copier.readthedocs.io/en/latest/) is required to use this template. Copier is an open source tool that hydrates projects from templates and natively supports updating projects as the original template matures. It's really neat!
 
-1) Install Python 3.7 or newer. (Check with `python --version`)
-2) Install Git 2.27 or new. (Check with `git --version`)
-3) Install `copier` like so: `pipx install copier`. (`pip` works fine too, but `pipx` is what the cool kids use)
-4) Create a new project using this template like so: `copier gh:lincc-frameworks/python-project-template <path/to/destination>`
-5) Provide answers to the prompts
-6) Enjoy pure, uncut euphoria.
 
-## Post-euphoria - Install your new package
+# Getting started
 
-Ok, ok, calm down. I know, it's really great. 
-You should go ahead and install your new project using these instructions:
-1) Create a new environment with your choice of environment managers (conda, virtualenv, etc.)
-2) Install the base dependencies: `pip install .`
-3) Install the extra developer dependencies: `pip install '.[dev]'` (Note - the single quotes around '.[dev]' may not be required for your system.)
+## Prerequisites
 
-## Version control and keeping your project up to date
+These prerequisites for Copier are defined [here](https://copier.readthedocs.io/en/latest/#installation).
+1) Python > 3.7
+2) Git > 2.27
+3) pipx (nice to have, conda and pip work too, but can be more difficult to reason about later)
 
-### Setup version control for your newly created project
+```
+>> python --version
+Python 3.10.9
 
-To appreciate the full power of Copier, push your newly created project into a github repository. There are lots of ways to do this, and but every environment is a snowflake.
-Fortunately, there are several how-to's available. Roughly speaking, the sequence of commands is:
-1) Run `git init`[^1] in your newly created project
-2) Run `git add .` to add all your new files and directories.
-3) Run `git commit` with a nice message.
-4) Create a new remote repository ([GitHub How-to](https://docs.github.com/en/get-started/quickstart/create-a-repo))
-5) Run `git remote ad origin https://github.com/<the_remote_project>/<the_remote_repository>`
-6) Run `git push origin <local_branch_name>`
+>> git --version
+git version 2.34.1
+
+>> which pipx
+/usr/bin/pipx
+```
+
+## Install Copier
+
+Given that you have all the prerequisites satisfied, go ahead and install Copier.
+```
+>> pipx install copier
+```
+
+## Create a new project from the template
+
+Choose where you would like to create your new project, and call copier with the template.
+```
+>> copier gh:lincc-frameworks/python-project-template <path/to/destination>
+```
+
+After providing answers to the prompts, Copier will hydrate a project template and save it in the specified location.
+
+## Create a new environment and install your new package
+
+Create a new environment with your choice of environment tools (virtualenv, conda, etc.). Activate it, and change into the package directory.
+
+Install the newly created python package. Use `pip` to install both the standard set of dependencies as well as the `[dev]` dependencies. (Note: depending on your system, you may not need the single quotes about '.[dev]')
+```
+>> pip install -e .
+...
+Lots of output
+...
+
+>> pip install '.[dev]'
+...
+Lots more output
+...
+```
+
+## Register pre-commit hooks
+
+The tool `pre-commit` is an industry standard that will execute a set of tests prior to completing a git commit action. For instance, pre-commit can run unit tests to verify code coverage or linters to ensure adherence to style guides. Pre-commit documentation can be found [here](https://pre-commit.com/index.html).
+
+```
+>> pre-commit install
+```
+
+## Add local version control to your project
+
+The process of setting up _local_ version control will look something like this:
+
+```
+>> git init[^1]
+Initialized empty Git repository in /path/to/destination/.git/
+>> git checkout -b initial_branch
+Switched to a new branch 'initial_branch'
+>> git add .
+>> git commit -m 'Initial commit'
+```
 
 [^1]: If you haven't already, you can run `git config --global init.defaultBranch <name>` so that your default branch name isn't `master`.
 
-### Keep your project up to date with changes to the original template.
+## Extra Credit - Push your work to GitHub
 
-Once the project is under version control you'll be able to keep your project up to date by running `copier update`. 
-Copier will automatically check to see if a newer version of the original template is available and if so the changes will then be automatically applied to your project. Neato!
+Create a new repository in GitHub: ([GitHub How-to](https://docs.github.com/en/get-started/quickstart/create-a-repo))
+
+```
+>> git remote add origin https://github.com/<the_remote_project>/<the_remote_repository>
+>> git push origin <local_branch_name>
+```
+
+Notice that when you create a PR in GitHub, a set of tests for Continuous Integration starts up to verify that the project can build successfully and that all the unit tests pass. Neato!
+
+
+# Some nifty things you get for free
+
+## Keep your project up to date as the original template evolves
+
+Once your project is under version control you'll be able to keep your project up to date by running `copier update`.
+
+Copier will automatically check to see if a newer version of the original template is available and if so the changes will be automatically applied. Neato!
 
 And of course, because your project is under version control, if you don't like the new changes, you can always revert back to the previous state. :)
 
-## Other neat peices that come for free
+## GitHub CI is ready out of the box
+
+Notice that this template contains a `.github/workflows` directory with a `python-package.yml` file. Because of this, any project created from this template that uses GitHub as a repository will automatically have CI enabled.
 
-### GitHub CI is ready out of the box
+GitHub workflows are extremely useful, for more information, check out the [About workflows](https://docs.github.com/en/actions/using-workflows/about-workflows) page.
 
-Notice that this template contains a `.github/workflows` directory with a `python-package.yml` file. So any project created from this template that uses github as a repository will automatically have CI enabled. GitHub workflows are extremely useful, for more information, check out the [About workflows](https://docs.github.com/en/actions/using-workflows/about-workflows) page.
+## Pre-commit is part of it too
 
-### Pre-commit is part of it too
+No one wants the embarrassment of committing a .py file without a trailing blank line :scream: You'll immediately have access to [pre-commit](https://pre-commit.com/), an industry standard third-party tool.
 
-Once you have created a new project from the template, and start coding, you can save yourself from the embarassment of say, not including a blank line at the end of your .py file, by using pre-commit checks.
-After you have successfully run `pip install '.[dev]'` as part of the "Post-euphoria - Install your new package" step, run `pre-commit install`.
-This will register all the pre-commit git hooks defined in .pre-commit-config.yaml with git so that they are run before a `git commit` is completed.
+Using pre-commit before GitHub workflows start allows you to do a quick check of your code before it's committed. This cuts down on code feedback time, and allows for faster development.
 
-This functionality relies on a the third-party tool, [pre-commit](https://pre-commit.com/). It's a very useful tool when paired with Github workflows. Since the workflows will typically prevent code merging if certain tests fail, by using pre-commit, the user can verify that their code will pass all the workflow checks prior to completing a git commit.
+# Contributing to the Template
 
-# Developement of the template
+## Find (or make) a new GitHub issue
 
-## Making updates to the template
+Add yourself as the assignee on an existing issue so that we know who's working on what. ( If you're not actively working on an issue, unassign yourself :wink: ) 
 
-Feel free to make updates to this template. Once you've tested the updates you should create a new release to make them available. GitHub's [instructions](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) for doing so are here. Use your best judgement when incrementing the version.
+If there isn't an issue for the work you want to do, please create one and include a description - it's just polite.
+
+## Create a branch
+
+It is preferable that you create a new branch with a name like `issue/##/<short-description>`. GitHub makes it pretty easy to associate branches and tickets, but it's just easier when it's in the name.
 
 ## Testing the template
 
-Testing can be tricky. The current best way is to clone this repository locally, and generate test projects locally, and verify your expected results. To be clear though, if there's an opportunity for automated tests, please take advantage of it.
+Testing can be tricky. The current best way is to clone this repository locally, and use Copier to generate a test project locally, then verify your expected results.
+
+Copier will look for git tags to determine which version of the template to use. You probably don't want to create new tags while you're working on the template. Create a test project using this signature to let Copier know to use the latest local version. See the [Copier documentation](https://copier.readthedocs.io/en/latest/generating/#regenerating-a-project) for more information.
+
+```
+>> copier --vcs-ref HEAD </local/path/to/template> </test/project/directory>
+```
+Notes:
+1) Any changes to the template will need to be committed (**not pushed**) to be picked up by Copier.
+2) If there's an opportunity for introducing an automated test, please take it.
+
+## Create your PR
+
+To be able to move quickly, there aren't many guardrails right now to prevent merging bad code. This will change as the project becomes more mature. For now, please use PR best practices, and get someone to review your code.
+
+## Optional - Release a new version
+
+Once you've tested the updates you should create a new release to make them available. GitHub's [instructions](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) for doing so are here. Use your best judgement when incrementing the version. i.e. is this a major, minor, or patch fix.

tests/{{module_name}}_tests/test_example_module.py.jinja

@@ -9,4 +9,4 @@ def test_greetings():
 def test_meaning():
     """Verify the output of the `meaning` function"""
     output = example_module.meaning()
-    assert output == 42
+    assert output == 42