diff options
Diffstat (limited to '')
| -rw-r--r-- | .gitlab-ci.yml | 12 | ||||
| -rw-r--r-- | .mdlrc | 1 | ||||
| -rw-r--r-- | CHANGELOG.md | 22 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 75 | ||||
| -rw-r--r-- | docs/README.md | 5 | ||||
| -rw-r--r-- | docs/setup.md | 36 |
6 files changed, 114 insertions, 37 deletions
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 710776c1..ae4c28e6 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -81,7 +81,7 @@ build-stretch-3.6: . - docker push $BASE_IMAGE_URL:stretch-3.6-$CI_COMMIT_REF_SLUG -lint: +lint-python: stage: lint image: $BASE_IMAGE_URL:alpine-3.7-$CI_COMMIT_REF_SLUG script: @@ -89,6 +89,16 @@ lint: tags: - docker +lint-markdown: + stage: lint + image: ruby:2.5-alpine + before_script: + - gem install mdl + script: + - mdl *.md **/*.md + tags: + - docker + test-3.7-alpine: <<: *test-template image: $BASE_IMAGE_URL:alpine-3.7-$CI_COMMIT_REF_SLUG @@ -0,0 +1 @@ +rules '~MD024' diff --git a/CHANGELOG.md b/CHANGELOG.md index 22e6e2d3..c59fe469 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,19 +1,39 @@ # 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 + +### Added + +- Markdown linting + +### Changed + +- Added unneded files to `.dockerignore` ## [0.3.0] - 2018-18-09 + ### Added + - Do not recommend pushes to `master` in `CONTRIBUTING.md` -- Documentation about how to set up the site and Postgres up locally using Docker and `pip` + +- Documentation about how to set up the site and + Postgres up locally using Docker and `pip` + - Healthchecks for the `app` container + - Require 100% code coverage in `CONTRIBUTING.md` + - Require `CHANGELOG.md` updates in `CONTRIBUTING.md` + - The `psmgr` console script as a shortcut to `python manage.py` + - This file ### Changed + - Improved build speed by not installing unneeded dependencies. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a800335..3a9b1dc8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,44 +1,69 @@ # Contributing to one of our projects -Our projects are open-source, and are deployed as commits are pushed to the `master` branch on each repository. -We've created a set of guidelines here in order to keep everything clean and in working order. Please note that -contributions may be rejected on the basis of a contributor failing to follow the guidelines. +Our projects are open-source, and are deployed as commits are +pushed to the `master` branch on each repository. We've created +a set of guidelines here in order to keep everything clean and +in working order. Please note that contributions may be rejected +on the basis of a contributor failing to follow the guidelines. ## Rules 1. **No force-pushes** or modifying the Git history in any way. -1. If you have direct access to the repository, **create a branch for your changes** and create a merge request for that branch. +1. If you have direct access to the repository, + **create a branch for your changes** and + create a merge request for that branch. If not, fork it and work on a separate branch there. - * Some repositories require this and will reject any direct pushes to `master`. Make this a habit! -1. If someone is working on a merge request, **do not open your own merge request for the same task**. Instead, leave some comments - on the existing merge request. Communication is key, and there's no point in two separate implementations of the same thing. - * One option is to fork the other contributor's repository, and submit your changes to their branch with your - own merge request. If you do this, we suggest following these guidelines when interacting with their repository - as well. -1. **Adhere to the prevailing code style**, which we enforce using [flake8](http://flake8.pycqa.org/en/latest/index.html). - * Additionally, run `flake8` against your code before you push it. Your commit will be rejected by the build server + * Some repositories require this and will reject + any direct pushes to `master`. Make this a habit! +1. If someone is working on a merge request, + **do not open your own merge request for the same task**. + Instead, leave some comments on the existing merge request. + Communication is key, and there's no point in two separate + implementations of the same thing. + * One option is to fork the other contributor's repository, + and submit your changes to their branch with your own merge + request. If you do this, we suggest following these guidelines + when interacting with their repository as well. +1. **Adhere to the prevailing code style**, which we enforce using + [flake8](http://flake8.pycqa.org/en/latest/index.html). + * Additionally, run `flake8` against your code before + you push it. Your commit will be rejected by the build server if it fails to lint. * Keep the coverage at 100%. Your reason not to do so is not good enough. - * No pushes to `master` without a really really good reason. If you're unsure, it is not good enough. - * Update the `CHANGELOG.md` file as necessary. Maintainers will tag releases as appropriate. -1. **Don't fight the framework**. Every framework has its flaws, but the frameworks we've picked out have been carefully - chosen for their particular merits. If you can avoid it, please resist reimplementing swathes of framework logic - the + * No pushes to `master` without a really really good reason. + If you're unsure, it is not good enough. + * Update the `CHANGELOG.md` file as necessary. + Maintainers will tag releases as appropriate. +1. **Don't fight the framework**. Every framework has its flaws, but + the frameworks we've picked out have been carefully + chosen for their particular merits. If you can avoid it, + please resist reimplementing swathes of framework logic - the work has already been done for you! -1. **Work as a team** and cooperate where possible. Keep things friendly, and help each other out - these are shared +1. **Work as a team** and cooperate where possible. Keep things + friendly, and help each other out - these are shared projects, and nobody likes to have their feet trodden on. -1. **Internal projects are internal**. As a contributor, you have access to information that the rest of the server - does not. With this trust comes responsibility - do not release any information you have learned as a result of - your contributor position. We are very strict about announcing things at specific times, and many staff members +1. **Internal projects are internal**. As a contributor, + you have access to information that the rest of the server + does not. With this trust comes responsibility - do not + release any information you have learned as a result of + your contributor position. We are very strict about + announcing things at specific times, and many staff members will not appreciate a disruption of the announcement schedule. -Above all, the needs of our community should come before the wants of an individual. Work together, build solutions to -problems and try to do so in a way that people can learn from easily. Abuse of our trust may result in the loss of your Contributor role, especially in relation to Rule 7. +Above all, the needs of our community should come before the wants +of an individual. Work together, build solutions to problems and +try to do so in a way that people can learn from easily. +Abuse of our trust may result in the loss of your +Contributor role, especially in relation to Rule 7. ## Changes to this arrangement -All projects evolve over time, and this contribution guide is no different. This document may also be subject to pull -requests or changes by contributors, where you believe you have something valuable to add or change. +All projects evolve over time, and this contribution +guide is no different. This document may also be subject to pull +requests or changes by contributors, where you +believe you have something valuable to add or change. ## Footnotes -This document was inspired by the [Glowstone contribution guidelines](https://github.com/GlowstoneMC/Glowstone/blob/dev/docs/CONTRIBUTING.md). +This document was inspired by the +[Glowstone contribution guidelines](https://github.com/GlowstoneMC/Glowstone/blob/dev/docs/CONTRIBUTING.md). diff --git a/docs/README.md b/docs/README.md index 6bef9c3c..2e9f15a1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,13 @@ # Documentation + This directory contains useful documentation for working with and using our site. ## Table of contents + * [Setup guide](setup.md) + * [PostgreSQL setup](setup.md#postgresql-setup) + * [Development with Docker](setup.md#development-with-docker) + * [Development with `pip`](setup.md#development-with-pip) diff --git a/docs/setup.md b/docs/setup.md index 16fb44d3..d6e5a7bf 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,41 +1,55 @@ # Setup -Setting up the Python site for local development is quick and easy using `pip`. -Alternatively, you can set it up using Docker. Both of these methods are documented here. + +Setting up the Python site for local development +is quick and easy using `pip`. +Alternatively, you can set it up using Docker. +Both of these methods are documented here. ## PostgreSQL setup -Install PostgreSQL according to its documentation. Then, create databases and users: + +Install PostgreSQL according to its documentation. +Then, create databases and users: + ```sql $ psql -qd postgres postgres=# CREATE USER pysite WITH CREATEDB; postgres=# CREATE DATABASE pysite OWNER pysite; ``` -Using different databases for development and tests is recommended because Django + +Using different databases for development +and tests is recommended because Django will expect an empty database when running tests. Now that PostgreSQL is set up, simply set the proper database URL in your environment variables: + ```sh -$ export DATABASE_URL=postgres://pysite@localhost/pysite +export DATABASE_URL=postgres://pysite@localhost/pysite ``` + A simpler approach to automatically configuring this might come in the near future - if you have any suggestions, please let us know! ## Development with Docker + To quickly set up the site locally, you can use Docker. -You will need Docker itself and `docker-compose` - you can omit the latter if you want to -use PostgreSQL on your host. Refer to the docker documentation on how to install Docker. +You will need Docker itself and `docker-compose` - +you can omit the latter if you want to use PostgreSQL on +your host. Refer to the docker documentation on how to install Docker. If you want to set the site up using `docker-compose`, simply run + ```sh -$ docker-compose up +docker-compose up ``` + and it will do its magic. Otherwise, you need to set a bunch of environment variables (or pass them along to the container). You will also need to have a running PostgreSQL instance if you want to run on your host's PostgreSQL instance. - ## Development with `pip` + This is the recommended way if you wish to quickly test your changes and don't want the overhead that Docker brings. @@ -45,9 +59,11 @@ using pip and virtualenv](https://packaging.python.org/guides/installing-using-p from the Python Packaging User Guide. Enter the virtual environment. Now you can run + ```sh -$ pip install -e .[lint,test] +pip install -e .[lint,test] ``` + to install base dependencies along with lint and test dependencies. You can either use `python manage.py` directly, or you can use the console |