[EVA-2020-02-2.git] / _bootstrap.md

* Python Library - library/name/__init__.py
* At least *one*  test - library/tests/test_setup.py
* Examples

# In Detail

To get started, copy the contents of this repository (excluding the .git directory) and run `_bootstrap.sh` to highlight substitutions you need to make.

Be careful to copy *all* files, including those starting with a . such as `.travis.yml`.

A Makefile is provided to automate some tests, checks and package building. You should use it!

## Library

### Structure

Libraries should be singleton if they pertain to a HAT or pHAT and class-based if they are for breakouts with selectable addresses.

A singleton library would work like this:

```
import library

library.do_something()
```

Whereas a class-based library requires an instance of its class:

```
import library

device = library.Library()

device.do_something()
```

### Linting

You should ensure you either run `flake8` while writing the library, or use an IDE/Editor with linting.

All libraries (and example code) should stick to PEP8 style guides, although you can ignore long line warnings (E501) if you feel they're unwarranted.

### Testing

At least one test script should be used to prevent obvious errors and omissions from creeping into the library.

You should use `tox` to run the test scripts:

```
sudo pip install tox
cd library/
tox
```

## Examples

Examples should use hyphens and short, descriptive names, ie: `rainbow-larson.py`

Examples should include a `print()` front-matter introducing them, ie:

```
print("""rainbow-larson.py - Display a larson scanning rainbow

Press Ctrl+C to exit.

""")
```

# Deployment

Before deploying you should `make python-testdeploy` and verify that the package looks good and is installable from test PyPi.

You should also `make check` to catch common errors, including mismatched version numbers, trailing whitespace and DOS line-endings.

Subsequent to deployment you should `git tag -a "vX.X.X" -m "Version X.X.X"` and `git push origin master --follow-tags` to tag a release on GitHub that matches the deployed code.
Commit	Line	Data
b3d40390 PH	1	* Python Library - library/name/__init__.py
	2	* At least one test - library/tests/test_setup.py
	3	* Examples
	4
	5	# In Detail
	6
	7	To get started, copy the contents of this repository (excluding the .git directory) and run `_bootstrap.sh` to highlight substitutions you need to make.
	8
	9	Be careful to copy all files, including those starting with a . such as `.travis.yml`.
	10
	11	A Makefile is provided to automate some tests, checks and package building. You should use it!
	12
	13	## Library
	14
	15	### Structure
	16
	17	Libraries should be singleton if they pertain to a HAT or pHAT and class-based if they are for breakouts with selectable addresses.
	18
	19	A singleton library would work like this:
	20
	21	```
	22	import library
	23
	24	library.do_something()
	25	```
	26
	27	Whereas a class-based library requires an instance of its class:
	28
	29	```
	30	import library
	31
	32	device = library.Library()
	33
	34	device.do_something()
	35	```
	36
	37	### Linting
	38
	39	You should ensure you either run `flake8` while writing the library, or use an IDE/Editor with linting.
	40
	41	All libraries (and example code) should stick to PEP8 style guides, although you can ignore long line warnings (E501) if you feel they're unwarranted.
	42
	43	### Testing
	44
	45	At least one test script should be used to prevent obvious errors and omissions from creeping into the library.
	46
	47	You should use `tox` to run the test scripts:
	48
	49	```
	50	sudo pip install tox
	51	cd library/
	52	tox
	53	```
	54
	55	## Examples
	56
	57	Examples should use hyphens and short, descriptive names, ie: `rainbow-larson.py`
	58
	59	Examples should include a `print()` front-matter introducing them, ie:
	60
	61	```
	62	print("""rainbow-larson.py - Display a larson scanning rainbow
	63
	64	Press Ctrl+C to exit.
65
66	""")
67	```
68
69	# Deployment
70
71	Before deploying you should `make python-testdeploy` and verify that the package looks good and is installable from test PyPi.
72
73	You should also `make check` to catch common errors, including mismatched version numbers, trailing whitespace and DOS line-endings.
74
75	Subsequent to deployment you should `git tag -a "vX.X.X" -m "Version X.X.X"` and `git push origin master --follow-tags` to tag a release on GitHub that matches the deployed code.