mybuddy/CONTRIBUTING.md

Contributing

• Contributions
  • Pull request process
• Development
  • Installation
  • Gulp Commands
  • Pre-commit Hook

Contributions

Contributions are accepted and encouraged via GitHub Issues and Pull Requests. Maintainers and users may also be found at babybuddy/Lobby on Gitter.

Pull request process

1. Fork this repository and commit your changes.
2. Make and commit tests for any new features or major functionality changes.
3. Run gulp lint and gulp test (see Gulp Commands) and ensure that all tests pass.
4. If changes are made to assets: build, collect and commit the /static folder (see Pre-commit Hook).
5. Open a new pull request 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
   

2. Install required Python packages, including dev packages

    pipenv install --dev
   

3. Install Gulp CLI

    npm install -g gulp-cli
   

4. Install required Node packages

    npm install
   

5. 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 for other settings and methods for defining them.

6. Migrate the database

    gulp migrate
   

7. 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 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 folder. Django's management commands are defined in the babybuddy/management/commands folder.

• gulp
• gulp build
• gulp clean
• gulp collectstatic
• gulp coverage
• gulp extras
• gulp fake
• gulp lint
• gulp makemigrations
• gulp migrate
• gulp reset
• gulp runserver
• gulp scripts
• gulp styles
• gulp 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 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 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.