Jazzband Contributing Guide (#37)

* remove non-tested django versions from the list of tested versions in the readme

* add snippet on generating SECRET_KEYs

* add contributing readme

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* add file filter for github actions lint-and-test workflow

* add path filters for the lint and test github actions workflow

* use path-ignore instead of path for file filters

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.github/workflows/lint-and-test.yml

@@ -1,6 +1,16 @@
 name: Lint & Test
 
-on: [push, pull_request]
+on:
+  pull_request:
+    paths-ignore:
+      - "LICENCE.txt"
+      - "**/*.md"
+      - ".pre-commit-config.yaml"
+  push:
+    paths-ignore:
+      - "LICENCE.txt"
+      - "**/*.md"
+      - ".pre-commit-config.yaml"
 
 permissions:
   contents: read

.gitignore

@@ -1,3 +1,12 @@
+# Python
+.Python
+.eggs/
+lib64/
+sdist/
+var/
+__pycache__/
+*$py.class
+*.so
 *.egg-info/
 *.pyc
 build/
@@ -7,3 +16,6 @@ dist/
 .ruff_cache
 .venv
 .venv_django_*
+
+# Node
+node_modules/

CONTRIBUTING.md

@@ -0,0 +1,33 @@
+[![Jazzband](https://jazzband.co/static/img/jazzband.svg)](https://jazzband.co/)
+
+This is a [Jazzband](https://jazzband.co/) project.
+By contributing you agree to abide by the [Contributor Code of Conduct](https://jazzband.co/about/conduct) and follow the [guidelines](https://jazzband.co/about/guidelines).
+
+## Contributing to Django Fernet Encrypted Fields
+
+We welcome contributions from the community to improve and maintain Django Fernet Encrypted Fields.
+Please follow these guidelines to ensure your contributions are accepted:
+
+1. **Fork the Repository**: Start by forking the repository to a personal/organization GitHub account.
+2. **Clone the Repository**: Clone the forked repository to your local machine.
+3. **Set Up the Environment**: Set up a virtual environment and install the necessary
+   dependencies for development and testing.
+   ```shell
+   $ python -m venv .venv
+   $ source .venv/bin/activate
+   $ pip install -r requirements.txt
+   ```
+4. **Install the pre-commit hooks**: We use [pre-commit](https://pre-commit.com/) to ensure code quality.
+   Install the pre-commit hooks by running:
+   ```shell
+   $ pre-commit install
+   ```
+5. **Create a Branch**: Create a new branch for the feature or bug fix.
+6. **Make Changes**: Make the changes and ensure they are well-documented.
+7. **Run Tests**: Ensure all tests pass before submitting a pull request.
+   ```shell
+   $ pip install coverage pytest
+   $ coverage3 run --source='./encrypted_fields' manage.py test
+   ```
+8. **Submit Pull Request**: Submit a pull request with a clear title, description of the changes,
+   motivations, and any relevant issue numbers.

README.md

@@ -39,6 +39,15 @@ SALT_KEY = [
 ]
 ```
 
+To generate a new `SECRET_KEY`, you can use Django's `get_random_secret_key` function.
+
+```python
+from django.core.management.utils import get_random_secret_key
+
+new_secret_key = get_random_secret_key()
+print(new_secret_key)
+```
+
 #### Rotating SECRET_KEY
 
 When you would want to rotate your `SECRET_KEY`, set the new value and put your old secret key value to `SECRET_KEY_FALLBACKS` list. That way the existing encrypted fields will still work, but when you re-save the field or create new record, it will be encrypted with the new secret key. (supported in Django >=4.1)
@@ -57,7 +66,8 @@ for obj in MyModel.objects.all():
 
 #### Available Fields
 
-Currently build in and unit-tested fields. They have the same APIs as their non-encrypted counterparts.
+Currently built-in and unit-tested fields include the following.
+They have the same APIs as their non-encrypted counterparts.
 
 - `EncryptedCharField`
 - `EncryptedTextField`
@@ -72,11 +82,15 @@ Currently build in and unit-tested fields. They have the same APIs as their non-
 
 | Compatible Django Version | Specifically tested | Python Version Required |
 | ------------------------- | ------------------- | ----------------------- |
-| `3.2`                     | :heavy_check_mark:  | 3.8+                    |
-| `4.0`                     | :heavy_check_mark:  | 3.8+                    |
-| `4.1`                     | :heavy_check_mark:  | 3.8+                    |
+| `3.2`                     |                     | 3.8+                    |
+| `4.0`                     |                     | 3.8+                    |
+| `4.1`                     |                     | 3.8+                    |
 | `4.2`                     | :heavy_check_mark:  | 3.8+                    |
-| `5.0`                     | :heavy_check_mark:  | 3.10+                   |
+| `5.0`                     |                     | 3.10+                   |
 | `5.1`                     | :heavy_check_mark:  | 3.10+                   |
 | `5.2`                     | :heavy_check_mark:  | 3.10+                   |
 | `6.0`                     | :heavy_check_mark:  | 3.12+                   |
+
+### Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.