Skip to content

Readme improvements #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 25, 2022
Merged

Readme improvements #8

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ This project contains sample code for a Python CLI app. It attempts to create a
[^1]: [Boring Python: dependency management](https://www.b-list.org/weblog/2022/may/13/boring-python-dependencies/)
[^2]: [Boring Python: code quality](https://www.b-list.org/weblog/2022/dec/19/boring-python-code-quality/)

## Features
## ✨Features

The following libraries and frameworks are configured and working out of the box.

Expand All @@ -33,7 +33,13 @@ The following libraries and frameworks are configured and working out of the box
- [EditorConfig](https://editorconfig.org/): Generic editor config.
- Some niceties for [VS Code](https://code.visualstudio.com/) (see below).

## Development environment
## ⚙️Setup

Do either of the following.

- __Use this template__ button on GitHub to create a new project
- __Open in a codespace__ button on GitHub to start playing with the project
- Download, copy, or clone the project

### Visual Studio Code

Expand All @@ -43,8 +49,6 @@ The fastest route to productivity will come from opening this project remotely i

Once the container is ready, the project will be buildable, lintable, and testable. Linting and formatting will be automatically done as you save. Check the _Problems_ tab for lint issues. Test cases will be automatically discovered in the _Testing_ tab. You can run all the tests or start debugging from here.

Alternatively, you can open the project in [Codespaces](https://github.com/features/codespaces) directly from GitHub. This will provide an identical Dev Container, but through VSCode on the browser. This is the fastest method to get your development environment up and running. However, the web editor is not as smooth as the native one.

If running locally instead, you will need Python3 with [hatch](https://github.com/pypa/hatch) (`pip install hatch`). In this scenario, it might be worthwhile to do the point VSCode to the Python interpreter of the dev environment in the project (`hatch run dev:python -c "import sys;print(sys.executable)"`).

### Other editors
Expand All @@ -65,7 +69,7 @@ pip install hatch
pip install pre-commit && pre-commit install-hooks
```

## Development cycle
## 💻Development cycle

- Run your CLI app

Expand All @@ -79,7 +83,7 @@ hatch run my-cli --help
hatch run dev:lint
```

- Run all tests and get coverage
- Run all tests

```shell
hatch run test:test
Expand All @@ -93,7 +97,7 @@ pre-submit run --all-files

Check out the example app code to get accustomed to the setup. You will need to change any name that starts with “my”, like _my description_.

## Continuous integration
## 🤖Continuous integration

There is a robust CI pipeline already setup. It contains the following jobs.

Expand All @@ -103,17 +107,17 @@ There is a robust CI pipeline already setup. It contains the following jobs.

Make sure your integration flow includes pull requests. Merge PRs only when the CI is successful, and you will have a good integration setup. Commit to main directly, and you will become a sad developer.

## Dependency management
## 📦Dependency management

All dependencies are pinned to a specific version. Dependabot will send occasional pull requests to update dependencies to available versions. Merge them only when CI is passing.

This is not a strict implementation of reproducible builds, since indirect dependencies are not locked to specific versions. If an indirect dependency has a new version that is incompatible with our app, it might break our integration. This will be remedied with a lock file once _hatch_ supports locking dependencies.

## Questions, Feedback, and Contributions
## 👋Help and contributions

I hope you will find this template useful. You can create an issue if you have a question, or if something is not working right for you. PRs are welcome if you would like to fix or add anything.

## Final thoughts and todos
## 🚩Roadmap

The project scaffolds a basic CLI application. You can build upon this for your own, or you can also strip the CLI parts altogether to build a different type of Python package. Actual templatign a la [Cookiecuter](https://www.cookiecutter.io/) could be useful.

Expand Down