diff --git a/README.md b/README.md index 55d6a28..6be3380 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,22 @@ -# Starting a new Python codebase? -This template takes the effort out of starting from a good place. +

+ ADACS Logo +

+ +

+ + Python 3.11 + + + Documentation Status + + + MIT License + +

+ +# Base Python Codebase Template + +**Starting a new Python codebase?** Read on to see how this template can have you set-up with all the elements of a professional codebase in less than 30 mins. ## Getting Started ***Installing the needed dependencies and building your new project is easy with the following steps ...*** diff --git a/docs/assets/adacs_logo.png b/docs/assets/adacs_logo.png new file mode 100644 index 0000000..1a4ade7 Binary files /dev/null and b/docs/assets/adacs_logo.png differ diff --git a/docs/content/common_gotchas.md b/docs/content/common_gotchas.md new file mode 100644 index 0000000..da6aa62 --- /dev/null +++ b/docs/content/common_gotchas.md @@ -0,0 +1,23 @@ +# Common Gotchas + +If you are encountering problems with a codebase rendered from this template, perhaps one of the +following is happening: + +## Configuring PyPI and TestPyPI + +### **'Entire account'-scoped secrets** + +'Entire account'-scoped tokens for *PyPI* (and *TestPyPI*) are not ideal, but there is a cold start problem when adding new projects to your account: you need a token to add a new project, but you need a project to create a project-scoped token. For this reason, you need to create and configure GitHub with a temporary 'Entire account'-scoped token first, and then when you have added the project to *PyPI* and *TestPyPi*, you need to delete the temporary token and repeat the process: create a token scoped to the project and reconfigure *GitHub* with the new secret. **It's easy to forget to do this.** + +## Workflow Issues + +### **My checks keep failing** + +Have you given workflows write permissions? If not, navigate within the repo to `Settings->Actions->General` and select `Read and write permissions`. + +## Developing Documentation + +### **I've added a new markdown file to the `docs/content` directory, but it isn't showing-up in the final rendered documentation** + +Have you added it to the `docs/index.rst` file? Follow the examples there for adding your new content +to the documentation. diff --git a/docs/index.rst b/docs/index.rst index 2725799..8f96e7b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,4 +11,5 @@ Home Configuring a new project Development guidelines + Common Gotchas Maintianing this template diff --git a/{{cookiecutter.repo_name}}/INSTRUCTIONS.template b/{{cookiecutter.repo_name}}/INSTRUCTIONS.template index 557d6ce..8847331 100644 --- a/{{cookiecutter.repo_name}}/INSTRUCTIONS.template +++ b/{{cookiecutter.repo_name}}/INSTRUCTIONS.template @@ -6,7 +6,7 @@ 1. **Create and activate a Python 3.11 environment** -Use your favourite method to create and activate a Python 3.11 environment for your development. +Use your favourite method to *create and activate* a Python 3.11 environment for your development. 2. **Install the project and all dependencies** @@ -14,49 +14,55 @@ With your environment activated, run the following from within your new repo: `p *NOTE: This needs to be done before any tests can be run, documentation built, etc.* -3. **Create a GitHub repo and adjust workflow permissions** +3. **Create a GitHub repo** -Goto *`https://github.com`* and create a new repo with the following: +If you have not yet done so, goto *`https://github.com`* and create a new repo with the following: - account: **{{cookiecutter.github_login}}** - repo name: **{{cookiecutter.repo_name}}** +4. **Adjust workflow permissions** + Navigate within the repo to `Settings->Actions->General` and select `Read and write permissions`. *NOTE: This needs to be done before the next stage so that the GitHub version bump action that is run on first upload does not fail.* -4. **Push the local repo to GitHub** +5. **Push the local repo to GitHub** Your new repo has been configured with your GitHub repo details. Run the following from within your new local repo to push it to GitHub: `git push -u origin main` *NOTE: If you notice any failed workflow runs at this point, it may be because you forgot to make the Action permission change mentioned above.* -5. **Configure branch permissions** +6. **Configure branch permissions** Navigate to `Settings->Branches->Add branch ruleset` and ... - give the Ruleset whatever name you'd like (e.g. `Protect Main`) - set `Enforecement status` to `Active` -- add a `Target Branch` targeting criteria by pattern and type `main` -- select `Require a pull request before merging` -- select `Require status checks to pass` and add the check `Run all build and unit tests` as a required check +- add a `Target Branch` via `Add target->Include by pattern` and type `main` +- adjust `Branch Rules` by selecting `Require a pull request before merging` +- adjust `Branch Rules` by selecting `Require status checks to pass` and add the check `Run all build and unit tests` as a required check - push the `Create` button at the bottom *From this point on, no development should be performed on the main branch. All updates to the main branch are managed via Pull Requests in the GitHub UI.* -6. **[Optional] Activate pre-commit git hooks** +7. **[Optional] Activate pre-commit git hooks** From within the repo, run the following: `pre-commit install` -7 **[Optional] Configure Services (Read The Docs, PyPI, etc.)** +8 **[Optional] Configure Services (Read The Docs, PyPI, etc.)** + +This can be done at any time when you want to enable these features; they are simply deactivated until you do; see *https://adacs-python-template.readthedocs.io/en/latest/content/configuring_services.html* for instructions. + +9. **Start developing!** -This can be done at any time when you want to enable these features; they are simply deactivated until you do; see *`https://adacs-python-template.readthedocs.io/en/latest/content/configuring_services.html`* for instructions. +No development should be done on the *main* branch, so create and checkout a new git branch with `git checkout -b new_branch_name` and start developing. -8. **Start developing!** +**N.B.: If you are new to the use of this template, make sure you have a good read of the following +sections of the documentation:** -**No development should be done on *main***, so create and checkout a new git branch with `git checkout -b new_branch_name` and start -developing. +- `Guidelines for Developing a New Project`: *https://adacs-base-python-template.readthedocs.io/en/latest/content/development_guidelines.html* +- `Common Gotchas`: *https://adacs-base-python-template.readthedocs.io/en/latest/content/common_gotchas.html* -**N.B.: If you are new to the use of this template, make sure you have a good read of the `Notes for Developer -If you have any questions, consult the template documentation at *`https://adacs-python-template.readthedocs.io/en/latest/index.html`*. +Any questions? Consult the docs at *https://adacs-base-python-template.readthedocs.io/en/latest/index.html*.