From dff0c7165ae28f02b4ab708f4c4644ef731bacbb Mon Sep 17 00:00:00 2001 From: Kevin Date: Thu, 28 Jul 2016 15:16:16 -0400 Subject: [PATCH 1/2] Adds Developer Documentation Signed-off-by: Kevin --- docs/Development/Contributing.md | 61 ++++++++++++++++++++++++++++++ docs/Development/DevEnvironment.md | 59 +++++++++++++++++++++++++++++ mkdocs.yml | 3 ++ 3 files changed, 123 insertions(+) create mode 100644 docs/Development/Contributing.md create mode 100644 docs/Development/DevEnvironment.md diff --git a/docs/Development/Contributing.md b/docs/Development/Contributing.md new file mode 100644 index 0000000..32df4c0 --- /dev/null +++ b/docs/Development/Contributing.md @@ -0,0 +1,61 @@ +# Contributing Guidelines + +## Types of Contributions + +### Report Bugs + +Report bugs at [https://github.com/StackFocus/PostMaster/issues](https://github.com/StackFocus/PostMaster/issues). + +If you are reporting a bug, please include: + + - Your operating system name and version. + - Any details about your local setup that might be helpful in troubleshooting. + - Detailed steps to reproduce the bug. + + +### Fix Bugs + +Look through the GitHub issues for bugs. Anything tagged with "bug" +is open to whoever wants to implement it. + +### Implement Features + +Look through the GitHub issues for features. Anything tagged with "feature" +is open to whoever wants to implement it. + +### Write Documentation + +PostMaster could always use more documentation. + +### Submit 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. + - 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. `$ python pylint-check.py` + 5. `$ py.test tests` + 6. Add, commit, and push + 7. Open pull request and describe what was changed + + +## 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. +`$ python pylint-check.py` + +There is a paradigm we've been using for Flask: + + - Keep the view as minimal as possible. + - 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..c0edd4d --- /dev/null +++ b/docs/Development/DevEnvironment.md @@ -0,0 +1,59 @@ +# Create your Environment + +We use [Vagrant](https://www.vagrantup.com/) and [Ansible](https://www.ansible.com/). + +Install Vagrant using your package manager. + +Provision the VM: + +``` +$ vagrant up +``` + +PostMaster should now be running on http://localhost:8080 +The default Postmaster login is `admin:PostMaster` + +Your instance is running a local mysql instance. +The default mysql login is `root:vagrant` + + +**NOTE:** The instance is not running a local mail server + + +If you do not want to use Vagrant, just run the ansible playbook against a host: +``` +$ ansible-playbook -i "localhost," \ +-c local /opt/postmaster/git/ops/ansible/site.yml \ +--extra-vars="remote_user=vagrant" \ +--extra-vars="provision_type=dev" +``` + +## Code Updates + +The code is location at: +`/opt/postmaster/git` + +### Activate the virtualenv +``` +$ source /opt/postmaster/env/bin/activate +``` + +### Apply the Code Updates +Your code repo is linked onto the VM, so updates are going to be there automatically, however each python file update will require you to restart the +service. On the vagrant host (`vagrant ssh`) + +``` +$ sudo service apache2 restart +``` + +### Run the test suite +``` +$ py.test tests +``` + +### Check Any Logs +``` +/opt/postmaster/logs/postmaster.log +/var/log/apache2/postmaster.access.log +/var/log/apache2/postmaster.error.log +``` 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 From 40d1e2cc7427f4e35e1f26fd8a2a8e072164337a Mon Sep 17 00:00:00 2001 From: PrahlM93 Date: Sun, 31 Jul 2016 19:10:15 -0700 Subject: [PATCH 2/2] Cleaned up the docs and removed Ansible section in DevEnvironment --- docs/Development/Contributing.md | 68 ++++++++++++++++-------------- docs/Development/DevEnvironment.md | 64 +++++++++++++++------------- docs/Installation/Docker.md | 2 - 3 files changed, 71 insertions(+), 63 deletions(-) diff --git a/docs/Development/Contributing.md b/docs/Development/Contributing.md index 32df4c0..2888e58 100644 --- a/docs/Development/Contributing.md +++ b/docs/Development/Contributing.md @@ -1,61 +1,67 @@ -# Contributing Guidelines +### Types of Contributions -## Types of Contributions +#### Bug Reports -### Report Bugs +Report bugs and issues at [https://github.com/StackFocus/PostMaster/issues](https://github.com/StackFocus/PostMaster/issues). -Report bugs at [https://github.com/StackFocus/PostMaster/issues](https://github.com/StackFocus/PostMaster/issues). +If you are reporting a bug, please include the following: -If you are reporting a bug, please include: + - 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 - - Your operating system name and version. - - Any details about your local setup that might be helpful in troubleshooting. - - Detailed steps to reproduce the bug. +#### Bug Fixes -### Fix Bugs +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. -Look through the GitHub issues for bugs. Anything tagged with "bug" -is open to whoever wants to implement it. +#### Features -### Implement 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". -Look through the GitHub issues for features. Anything tagged with "feature" -is open to whoever wants to implement it. +#### Documentation -### Write 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. -PostMaster could always use more documentation. - -### Submit Feedback +#### 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. - - Keep the scope as narrow as possible, to make it easier to implement. + - 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 +### 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. `$ python pylint-check.py` - 5. `$ py.test tests` - 6. Add, commit, and push - 7. Open pull request and describe what was changed + 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 +### 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. +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 view as minimal as possible. + - 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) + - 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 index c0edd4d..c0a0f3b 100644 --- a/docs/Development/DevEnvironment.md +++ b/docs/Development/DevEnvironment.md @@ -1,59 +1,63 @@ -# Create your Environment +### Overview -We use [Vagrant](https://www.vagrantup.com/) and [Ansible](https://www.ansible.com/). +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. -Install Vagrant using your package manager. +### Getting Started -Provision the VM: +- Install Vagrant by using your package manager or downloading it at: +[https://www.vagrantup.com/downloads.html](https://www.vagrantup.com/downloads.html) -``` -$ vagrant up -``` +- Run `vagrant up` as root/administrator to provision a Vagrant guest (development VM) -PostMaster should now be running on http://localhost:8080 -The default Postmaster login is `admin:PostMaster` +- Access PostMaster at [http://localhost:8080](http://localhost:8080) via your web browser -Your instance is running a local mysql instance. -The default mysql login is `root:vagrant` +- 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/) -**NOTE:** The instance is not running a local mail server +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 -If you do not want to use Vagrant, just run the ansible playbook against a host: -``` -$ ansible-playbook -i "localhost," \ --c local /opt/postmaster/git/ops/ansible/site.yml \ ---extra-vars="remote_user=vagrant" \ ---extra-vars="provision_type=dev" -``` -## Code Updates +#### Code Updates -The code is location at: -`/opt/postmaster/git` +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 + +#### Activate the virtualenv + +On the guest, run the following: ``` $ source /opt/postmaster/env/bin/activate ``` -### Apply the Code Updates -Your code repo is linked onto the VM, so updates are going to be there automatically, however each python file update will require you to restart the -service. On the vagrant host (`vagrant ssh`) +#### 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 test suite +#### Run the Unit Tests + +On the Vagrant guest, activate the virtualenv (see above) and run the following in "/opt/postmaster/git": ``` $ py.test tests ``` -### Check Any Logs +#### Checking Logs + +Logs can be found on the Vagrant guest at the following locations: ``` /opt/postmaster/logs/postmaster.log -/var/log/apache2/postmaster.access.log -/var/log/apache2/postmaster.error.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.