From 812edd196fdfa797de187c63b27ed52d1574c4b4 Mon Sep 17 00:00:00 2001 From: David Stephens Date: Sat, 10 Sep 2022 15:28:41 +0100 Subject: [PATCH] Update contributing docs --- CONTRIBUTING.md | 40 +++++++++++++++++----------------------- 1 file changed, 17 insertions(+), 23 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7ccd1b89..d17c8595 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,28 +2,22 @@ Contributing to Ansible-NAS is easy! Add your functionality, then raise a pull request on GitHub. A few things to bear in mind: -* **Restrict pull requests to one piece of functionality or bugfix at a time.** -* Test your new functionality or bugfix using the included `tests/test-vagrant.sh` script to spin up a test VM. -* Run `ansible-lint` against the playbook before committing. (There is a VSCode task set up to run the right command for you) -* Ensure that your PR only changes files required for your functionality or bugfix. Random changes in other files will result in your PR being rejected - -If you're adding a new application: - -* It must be structured in an [Ansible role](https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html). -* Ensure that the new application is disabled by default. -* Add a documentation page to `docs/applications/` - use an existing application as an example. -* Add to the list of Available Applications in `README.md` -* Add the frontend port to `docs/configuration/application_ports.md`, ensuring you've not clashed with an existing application. - -## Things to bear in mind - -* If you break the build with your PR, it'll need to be fixed before it's merged. -* Pull requests that unintentionally touch files, or that show files as removed then re-added will be rejected. -* Don't mess with line endings, or tabs vs. spaces. -* Please know that your efforts are appreciated, thanks! :+1: - ## Development Environment -* Development of Ansible-NAS is carried out in [Visual Studio Code](https://code.visualstudio.com/) - you'll get some nice -recommended extensions and task setups if you do the same. -* You'll need a working Python 3 environment, and [pre-commit](https://pre-commit.com) installed - `pip install -r requirements-dev.txt`. +* Development of Ansible-NAS is carried out in [Visual Studio Code](https://code.visualstudio.com/) on Linux - you'll get some nice recommended extensions and task setups if you do the same. +* You'll need a working Python 3 environment, Docker (to run tests) and [pre-commit](https://pre-commit.com) installed - `pip install -r requirements-dev.txt`. + +## General Stuff + +* **Restrict pull requests to one piece of functionality or bugfix at a time.** +* Ensure that your changes aren't going to break the GitHub builds. You can run the Pre-commit checks manually (it's not yet configured to run on every commit) using the VSCode task. +* Ensure that your PR only changes files required for your functionality or bugfix. Random changes in other files will result in your PR being rejected. +* Don't mess with line endings, or change spaces for tabs. They're fine how they are. +* Please know that your efforts are appreciated, thanks! :+1: + +## Adding a new application + +So you want to add a new application. Great! + +* Start by looking at the `hello_world` example. Following this structure is the most likely way of getting your PR approved. Leaving out things the `hello_world` example includes (ie docs, tests) will definitely result in your PR being rejected. +* Add to the list of Available Applications in `README.md`