diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..ed80dad4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,213 @@ +# Contributing + +[![Build Status](https://travis-ci.org/cdubz/babybuddy.svg?branch=master)](https://travis-ci.org/cdubz/babybuddy) +[![Coverage Status](https://coveralls.io/repos/github/cdubz/babybuddy/badge.svg?branch=master)](https://coveralls.io/github/cdubz/babybuddy?branch=master) +[![License](https://img.shields.io/badge/License-BSD%202--Clause-orange.svg)](https://opensource.org/licenses/BSD-2-Clause) +[![Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/babybuddy/Lobby) + +- [Contributions](#contributions) + - [Pull request process](#pull-request-process) +- [Development](#development) + - [Installation](#installation) + - [Gulp Commands](#gulp-commands) + - [Pre-commit Hook](#pre-commit-hook) + +## Contributions + +Contributions are accepted and encouraged via GitHub +[Issues](https://github.com/cdubz/babybuddy/issues) and +[Pull Requests](https://github.com/cdubz/babybuddy/pulls). Maintainers and users +may also be found at [babybuddy/Lobby](https://gitter.im/babybuddy/Lobby) on +Gitter. + +### Pull request process + +1. Fork this repository and commit your changes. +1. Make and commit tests for any new features or major functionality changes. +1. Run `gulp lint` and `gulp test` (see [Gulp Commands](#gulp-commands)) and + ensure that all tests pass. +1. If changes are made to assets: build, collect and commit the `/static` + folder (see [Pre-commit Hook](#pre-commit-hook)). +1. Open a [new pull request](https://github.com/cdubz/babybuddy/compare) against + the `master` branch. + +New pull requests will be reviewed by project maintainers as soon as possible +and we will do our best to provide feedback and support potential contributors. + +## Development + +### Requirements + +- Python 3.5+, pip, pipenv +- NodeJS 8.x and NPM 5.x +- Gulp + +### Installation + +1. Install pipenv + + pip install pipenv + +1. Install required Python packages, including dev packages + + pipenv install --dev + +1. Install Gulp CLI + + npm install -g gulp-cli + +1. Install required Node packages + + npm install + +1. Set, at least, the `DJANGO_SETTINGS_MODULE` environment variable + + export DJANGO_SETTINGS_MODULE=babybuddy.settings.development + + This process will differ based on the host OS. The above example is for + Linux-based systems. See [Configuration](#configuration) for other settings + and methods for defining them. + +1. Migrate the database + + gulp migrate + +1. Build assets and run the server + + gulp + + This command will also watch for file system changes to rebuild assets and + restart the server as needed. + +Open [http://127.0.0.1:8000](http://127.0.0.1:8000) and log in with the default +user name and password (`admin`/`admin`). + +### Gulp commands + +Baby Buddy's Gulp commands are defined and configured by files in the +[`gulpfile.js`](gulpfile.js) folder. Django's management commands are defined +in the [`babybuddy/management/commands`](babybuddy/management/commands) folder. + +- [`gulp`](#gulp) +- [`gulp build`](#build) +- [`gulp clean`](#clean) +- [`gulp collectstatic`](#collectstatic) +- [`gulp coverage`](#coverage) +- [`gulp extras`](#extras) +- [`gulp fake`](#fake) +- [`gulp lint`](#lint) +- [`gulp makemigrations`](#makemigrations) +- [`gulp migrate`](#migrate) +- [`gulp reset`](#reset) +- [`gulp runserver`](#runserver) +- [`gulp scripts`](#scripts) +- [`gulp styles`](#styles) +- [`gulp test`](#test) + +#### `gulp` + +Executes the `build` and `watch` commands and runs Django's development server. + +#### `build` + +Creates all script, style and "extra" assets and places them in the +`babybuddy/static` folder. + +#### `clean` + +Deletes all build folders and the root `static` folder. Generally this should +be run before a `gulp build` to remove previous build files and the generated +static assets. + +#### `collectstatic` + +Executes Django's `collectstatic` management task. This task relies on files in +the `babybuddy/static` folder, so generally `gulp build` should be run before +this command for production deployments. Gulp also passes along +non-overlapping arguments for this command, e.g. `--no-input`. + +#### `coverage` + +Create a test coverage report. See [`.coveragerc`](.coveragerc) for default +settings information. + +#### `extras` + +Copies "extra" files (fonts, images and server root contents) to the build +folder. + +#### `fake` + +Adds some fake data to the database. By default, ``fake`` creates one child and +31 days of random data. Use the `--children` and `--days` flags to change the +default values, e.g. `gulp fake --children 5 --days 7` to generate five fake +children and seven days of data for each. + +#### `lint` + +Executes Python and SASS linting for all relevant source files. + +#### `makemigrations` + +Executes Django's `makemigrations` management task. Gulp also passes along +non-overlapping arguments for this command. + +#### `migrate` + +Executes Django's `migrate` management task. In addition to migrating the +database, this command creates the default `admin` user. Gulp also passes along +non-overlapping arguments for this command. + +#### `reset` + +Resets the database to a default state *with* one fake child and 31 days of +fake data. + +#### `runserver` + +Executes Django's `runserver` management task. Gulp also passes along +non-overlapping arguments for this command. + +#### `scripts` + +Builds and combines relevant application scripts. Generally this command does +not need to be executed independently - see the `build` command. + +#### `styles` + +Builds and combines SASS styles in to CSS files. Generally this command does +not need to be executed independently - see the `build` command. + +#### `test` + +Executes Baby Buddy's suite of tests. + +Gulp also passes along non-overlapping arguments for this command, however +individual tests cannot be run with this command. `python manage.py test` can be +used for individual test execution. + +### Pre-commit Hook + +A [pre-commit hook](https://git-scm.com/docs/githooks#_pre_commit) is +recommended for all commits in order to make sure that static assets are +correctly committed. Here is an example working script for bash: + +``` +#!/bin/bash + +if [ $(git diff --cached --name-only | grep static_src -c) -ne 0 ] +then + gulp clean && gulp build && gulp collectstatic + if [ $? -ne 0 ]; then exit $?; fi + git add ./static +fi + +gulp lint && gulp test + +exit $? +``` + +This script will build and add static assets to the commit only if changes have +been made to files in a `static_src` directory of the project. It will always +run the `gulp lint` and `gulp test` commands. If any of these processes result +in an error, the commit will be rejected. diff --git a/README.md b/README.md index 9e1418ce..b3083819 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,6 @@ # Baby Buddy -[![Build Status](https://travis-ci.org/cdubz/babybuddy.svg?branch=master)](https://travis-ci.org/cdubz/babybuddy) -[![Coverage Status](https://coveralls.io/repos/github/cdubz/babybuddy/badge.svg?branch=master)](https://coveralls.io/github/cdubz/babybuddy?branch=master) -[![License](https://img.shields.io/badge/License-BSD%202--Clause-orange.svg)](https://opensource.org/licenses/BSD-2-Clause) -[![Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/babybuddy/Lobby) - A buddy for babies! Helps caregivers track sleep, feedings, diaper changes, and tummy time to learn about and predict baby's needs without (*as much*) guess work. @@ -29,10 +24,7 @@ work. - [`GET` Method](#get-method) - [`OPTIONS` Method](#options-method) - [`POST` Method](#post-method) -- [Development](#development) - - [Installation](#installation) - - [Gulp Commands](#gulp-commands) - - [Pre-commit Hook](#pre-commit-hook) +- [Contributing](#contributing) ## Demo @@ -106,7 +98,7 @@ containers - one for the database and one for the application. The app should now be locally available at [http://127.0.0.1:8000](http://127.0.0.1:8000). See [Get Started, Part 6: Deploy your app](https://docs.docker.com/get-started/part6/) -for detailed information about how to deployment methods with Docker. +for detailed information about deployment methods with Docker. ### Heroku @@ -493,180 +485,7 @@ error details if errors exist. Errors are keyed by either the field in error or the general string "non_field_errors" (usually when validation incorporates multiple fields). -## Development +## Contributing -### Requirements - -- Python 3.5+, pip, pipenv -- NodeJS 8.x and NPM 5.x -- Gulp - -### Installation - -1. Install pipenv - - pip install pipenv - -1. Install required Python packages, including dev packages - - pipenv install --dev - -1. Install Gulp CLI - - npm install -g gulp-cli - -1. Install required Node packages - - npm install - -1. Set, at least, the `DJANGO_SETTINGS_MODULE` environment variable - - export DJANGO_SETTINGS_MODULE=babybuddy.settings.development - - This process will differ based on the host OS. The above example is for - Linux-based systems. See [Configuration](#configuration) for other settings - and methods for defining them. - -1. Migrate the database - - gulp migrate - -1. Build assets and run the server - - gulp - - This command will also watch for file system changes to rebuild assets and - restart the server as needed. - -Open [http://127.0.0.1:8000](http://127.0.0.1:8000) and log in with the default -user name and password (`admin`/`admin`). - -### Gulp commands - -Baby Buddy's Gulp commands are defined and configured by files in the -[`gulpfile.js`](gulpfile.js) folder. Django's management commands are defined -in the [`babybuddy/management/commands`](babybuddy/management/commands) folder. - -- [`gulp`](#gulp) -- [`gulp build`](#build) -- [`gulp clean`](#clean) -- [`gulp collectstatic`](#collectstatic) -- [`gulp coverage`](#coverage) -- [`gulp extras`](#extras) -- [`gulp fake`](#fake) -- [`gulp lint`](#lint) -- [`gulp makemigrations`](#makemigrations) -- [`gulp migrate`](#migrate) -- [`gulp reset`](#reset) -- [`gulp runserver`](#runserver) -- [`gulp scripts`](#scripts) -- [`gulp styles`](#styles) -- [`gulp test`](#test) - -#### `gulp` - -Executes the `build` and `watch` commands and runs Django's development server. - -#### `build` - -Creates all script, style and "extra" assets and places them in the -`babybuddy/static` folder. - -#### `clean` - -Deletes all build folders and the root `static` folder. Generally this should -be run before a `gulp build` to remove previous build files and the generated -static assets. - -#### `collectstatic` - -Executes Django's `collectstatic` management task. This task relies on files in -the `babybuddy/static` folder, so generally `gulp build` should be run before -this command for production deployments. Gulp also passes along -non-overlapping arguments for this command, e.g. `--no-input`. - -#### `coverage` - -Create a test coverage report. See [`.coveragerc`](.coveragerc) for default -settings information. - -#### `extras` - -Copies "extra" files (fonts, images and server root contents) to the build -folder. - -#### `fake` - -Adds some fake data to the database. By default, ``fake`` creates one child and -31 days of random data. Use the `--children` and `--days` flags to change the -default values, e.g. `gulp fake --children 5 --days 7` to generate five fake -children and seven days of data for each. - -#### `lint` - -Executes Python and SASS linting for all relevant source files. - -#### `makemigrations` - -Executes Django's `makemigrations` management task. Gulp also passes along -non-overlapping arguments for this command. - -#### `migrate` - -Executes Django's `migrate` management task. In addition to migrating the -database, this command creates the default `admin` user. Gulp also passes along -non-overlapping arguments for this command. - -#### `reset` - -Resets the database to a default state *with* one fake child and 31 days of -fake data. - -#### `runserver` - -Executes Django's `runserver` management task. Gulp also passes along -non-overlapping arguments for this command. - -#### `scripts` - -Builds and combines relevant application scripts. Generally this command does -not need to be executed independently - see the `build` command. - -#### `styles` - -Builds and combines SASS styles in to CSS files. Generally this command does -not need to be executed independently - see the `build` command. - -#### `test` - -Executes Baby Buddy's suite of tests. - -Gulp also passes along non-overlapping arguments for this command, however -individual tests cannot be run with this command. `python manage.py test` can be -used for individual test execution. - -### Pre-commit Hook - -A [pre-commit hook](https://git-scm.com/docs/githooks#_pre_commit) is -recommended for all commits in order to make sure that static assets are -correctly committed. Here is an example working script for bash: - -``` -#!/bin/bash - -if [ $(git diff --cached --name-only | grep static_src -c) -ne 0 ] -then - gulp clean && gulp build && gulp collectstatic - if [ $? -ne 0 ]; then exit $?; fi - git add ./static -fi - -gulp lint && gulp test - -exit $? -``` - -This script will build and add static assets to the commit only if changes have -been made to files in a `static_src` directory of the project. It will always -run the `gulp lint` and `gulp test` commands. If any of these processes result -in an error, the commit will be rejected. +Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed +information about how to develop and contribute to Baby Buddy.