Merge pull request #27 from torchbox/improve-developer-documentation

Improve developer documentation

Author: nickmoreton

.gitignore

@@ -7,3 +7,4 @@ dist/
 .python-version
 .coverage
 .venv
+venv

.pre-commit-config.yaml

@@ -1,21 +1,21 @@
+default_language_version:
+  node: system
+  python: python3.9
 repos:
   - repo: https://github.com/python/black
     rev: 22.3.0
     hooks:
       - id: black
-        language_version: python3.8
         exclude: migrations/
   - repo: https://github.com/timothycrosley/isort
     rev: 5.12.0
     hooks:
       - id: isort
-        language_version: python3.8
   - repo: https://github.com/pycqa/flake8
     # flake8 config is in setup.cfg
     rev: 6.0.0
     hooks:
       - id: flake8
-        language_version: python3.8
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v2.3.2
     hooks:

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]

README.md

@@ -1,4 +1,4 @@
-![tests](https://github.com/kevinhowbrook/wagtail-jotform/workflows/Tests/badge.svg)
+![tests](https://github.com/torchbox/wagtail-jotform/workflows/Tests/badge.svg)
 [![codecov](https://codecov.io/gh/kevinhowbrook/wagtail-jotform/branch/master/graph/badge.svg?token=GBDM9H1A2X)](https://codecov.io/gh/kevinhowbrook/wagtail-jotform)
 [![black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Total alerts](https://img.shields.io/lgtm/alerts/g/kevinhowbrook/wagtail-jotform.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/kevinhowbrook/wagtail-jotform/alerts/)
 
@@ -12,7 +12,7 @@ Wagtail Jotform works by providing a new `EmbeddedFormPage` page type with a for
 
 Install from [pypi](https://pypi.org/project/wagtail-jotform/):
 
-```
+```bash
 pip install wagtail-jotform
 ```
 
@@ -52,29 +52,21 @@ When a form is created, the Jotform `thankurl` is set with your created form's t
 
 Wagtail Jotform has two templates:
 
-```
-embedded_form_page.html
-thank_you.html
-```
+- embedded_form_page.html
+- thank_you.html
 
 You can override these templates in your project by adding them in the following location:
 
-```
-your_project_root/
-  templates/
-    wagtail_jotform/
-        embed_form_page.html
-        thank_you.html
-```
+- your_project_root/
+  - templates/
+    - wagtail_jotform/
+      - embed_form_page.html
+      - thank_you.html
 
-## Tests
+## Contributing
 
-```
-# Install the development environment
-poetry install
-poetry shell
+We welcome contributions to this project. Please follow the [contributing instructions](docs/CONTRIBUTING.md) to get started.
 
-# Run the tests
-coverage run ./runtests.py
-coverage report
-```
+## Release process
+
+To release a new version, the [Release documentation](docs/RELEASE.md) should be followed.

docs/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Contributions are welcome, please follow the setup instructions below to get started.
+
+## Setup
+
+### Clone the repository
+
+```bash
+git clone https://github.com/torchbox/wagtail-jotform
+```
+
+### Create a virtual environment and install the requirements
+
+```bash
+cd wagtail-jotform
+python3 -m venv venv
+source venv/bin/activate
+pip install -e ".[testing,development]"
+```
+
+### Install the pre-commit hooks
+
+```bash
+pre-commit install
+```
+
+### Do some work, write some tests
+
+Change some code, write some tests, and check that the tests pass
+
+### Run the tests
+
+```bash
+coverage run ./runtests.py
+coverage report
+```

docs/RELEASE.md

@@ -0,0 +1,13 @@
+# Release
+
+The release process is run with github actions. To release a new version:
+
+1. Update the version number in `wagtail_jotform/__init__.py`
+
+2. Update the changelog in `docs/CHANGELOG.md`
+
+3. Commit and push the changes
+
+4. Create a new release in github, with the tag name `X.X.X` and the release title `X.X.X`
+
+5. The release will be built and published to pypi automatically