diff --git a/docs/Development/Contributing.md b/docs/Development/Contributing.md new file mode 100644 index 0000000..2888e58 --- /dev/null +++ b/docs/Development/Contributing.md @@ -0,0 +1,67 @@ +### Types of Contributions + +#### Bug Reports + +Report bugs and issues at [https://github.com/StackFocus/PostMaster/issues](https://github.com/StackFocus/PostMaster/issues). + +If you are reporting a bug, please include the following: + + - The version of PostMaster that you are running + - The operating system name and version that is running the application + - The version of Python that is running the application (`python -V`) + - The installation method used (package or manual) + - Detailed steps to reproduce the bug + - Any details about your specific environment that might be helpful for troubleshooting + + +#### Bug Fixes + +Look through the GitHub issues for bugs. +Anything tagged with "bug" and is unassigned is open to whoever wants to implement it. +Any changes made should be documented in docs/ChangeLog.md. + +#### Features + +Look through the GitHub issues for features. +Anything tagged with "feature" and is unassigned is open to whoever wants to implement it. +Any changes made should be documented in "docs/ChangeLog.md". + +#### Documentation + +PostMaster documentation is written in Markdown and then deployed to GitHub pages via mkdocs by a StackFocus administrator. +To update documentation, directly modify the Markdown files in the "docs" folder. Once the changes are merged, +a StackFocus administrator will update GitHub pages. + +#### Feedback + +The best way to send feedback is to file an issue at [https://github.com/StackFocus/PostMaster/issues](https://github.com/StackFocus/PostMaster/issues). + +If you are proposing a feature: + + - Explain in detail how it would work and why it would be beneficial + - Keep the scope as narrow as possible to make it easier to implement + +### How To Contribute Code + + 1. Fork the project + 2. Create a branch related to the issue (ex. ft-adds_2factor-123) + 3. Make changes to the code + 4. Write unit tests to test the new code + 5. Run `$ python pylint-check.py` to verify that you are complying to PEP8 coding standards + 6. Run `$ py.test tests` to verify the unit tests pass + 7. Commit and push the changed files + 8. Open a pull request and describe what was changed (try to squash your commits when possible) + + +### Coding Standards +We use standard [PEP8](https://www.python.org/dev/peps/pep-0008/). +Our specific exceptions are in the `.pylintrc` file. + +Code will not be accepted if it fails the pylint test. To run pylint: +`$ python pylint-check.py` + +There is a paradigm we've been using for Flask: + + - Keep the code in the routes as minimal as possible by using decorators and helper functions + - Use Ajax to an API route for data as much as possible + - Use modern Flask and SQLAlchemy functions for API routes (ex. get_or_404) diff --git a/docs/Development/DevEnvironment.md b/docs/Development/DevEnvironment.md new file mode 100644 index 0000000..c0a0f3b --- /dev/null +++ b/docs/Development/DevEnvironment.md @@ -0,0 +1,63 @@ +### Overview + +PostMaster uses a combination of [Vagrant](https://www.vagrantup.com/) and [Ansible](https://www.ansible.com/) to +automate the setup of a development environment. In this scenario, Ansible is run entirely on the guest, and is thus +not required on the host system. + +### Getting Started + +- Install Vagrant by using your package manager or downloading it at: +[https://www.vagrantup.com/downloads.html](https://www.vagrantup.com/downloads.html) + +- Run `vagrant up` as root/administrator to provision a Vagrant guest (development VM) + +- Access PostMaster at [http://localhost:8080](http://localhost:8080) via your web browser + +- Login using the username "admin" and the password "PostMaster" + +- For more help with Vagrant, such as deleting and recreating your development environment, visit +[https://www.vagrantup.com/docs/cli/](https://www.vagrantup.com/docs/cli/) + + +Additional Information: + +- The Vagrant guest is running a local MySQL instance which can be accessed locally with `mysql -uroot -pvagrant` +- The Vagrant guest is not running a mail server + + +#### Code Updates + +The source code is located on the Vagrant guest at `/opt/postmaster/git`, but code changes made locally +will be automatically synced to the development VM via Vagrant. + + +#### Activate the virtualenv + +On the guest, run the following: +``` +$ source /opt/postmaster/env/bin/activate +``` + +#### Apply the Code Updates +Any Python file updates will require you to restart Apache on the Vagrant guest. To do so, run the following on +the Vagrant guest: + +``` +$ sudo service apache2 restart +``` + +#### Run the Unit Tests + +On the Vagrant guest, activate the virtualenv (see above) and run the following in "/opt/postmaster/git": +``` +$ py.test tests +``` + +#### Checking Logs + +Logs can be found on the Vagrant guest at the following locations: +``` +/opt/postmaster/logs/postmaster.log +/opt/postmaster/logs/postmaster.access.log +/opt/postmaster/logs/postmaster.error.log +``` diff --git a/docs/Installation/Docker.md b/docs/Installation/Docker.md index 9afcce1..a51882d 100644 --- a/docs/Installation/Docker.md +++ b/docs/Installation/Docker.md @@ -1,5 +1,3 @@ -### Overview - ### Prerequisites 1. An Ubuntu 14.04 mail server configured with the guide from [DigitalOcean](https://www.digitalocean.com/community/tutorials/how-to-configure-a-mail-server-using-postfix-dovecot-mysql-and-spamassassin) or [Linode](https://www.linode.com/docs/email/postfix/email-with-postfix-dovecot-and-mysql). Any other MySQL configuration requires edits to PostMaster's database models. Paid support for this is available. diff --git a/mkdocs.yml b/mkdocs.yml index 873afea..b31cb95 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,5 +15,8 @@ pages: - Configurations Page: Configuration/ConfigurationsPage.md - API: - API Usage: API/ApiUsage.md +- Developer Guide: + - Dev Environment: Development/DevEnvironment.md + - Contributing: Development/Contributing.md - Release Notes: - Change Log: ChangeLog.md