Skip to content

Latest commit

 

History

History
239 lines (166 loc) · 9.04 KB

CONTRIBUTING.md

File metadata and controls

239 lines (166 loc) · 9.04 KB
Raw

Contributing

Here you'll find the steps you need to take to set up your development environment as well as instructions for coding standards and contributing guidelines.

You'll notice that when this file is present, GitHub will give you an alert when creating a new issue, indicating that you should check out the guidelines before contributing.

Development Environment

Prerequesites

You must install and configure the following packages on your development machine:

In order to extend veinapp's functionality you should install Angular CLI:

# Uninstall any previous version
npm uninstall -g angular-cli @angular/cli

# Clear entire cache
npm cache clean

# Install Angular CLI globally
npm install -g @angular/cli@latest

See Resources section for more information on Angular CLI.

Set up instructions

This application relies on Firebase Realtime Database as its data store. So first sign in to Firebase, head to the console and create your project. Then grab your initialization data.

This application also relies on Mapzen as its geocoding service provider. Create a Mapzen developer account and grab your API key as explained here.

Fork the main Veinapp repository from GitHub and then...

# Clone your fork (https://help.github.com/articles/cloning-a-repository/):
git clone [email protected]:<github username>/veinapp.git

# Go to the project directory:
cd veinapp

# Add the main Veinapp repository as an upstream remote to your repository:
git remote add upstream https://github.com/adab1ts/veinapp.git

# Tell local git to get information about upstream remote:
git fetch upstream

# Point local copy of master branch to upstream to be able to pull the latest changes of upstream repository:
git branch --set-upstream-to=upstream/master master

# Check that your local branches track the proper remotes:
git branch -vv

# Install project dependencies:
npm install

# Edit Mapzen configuration files and update it with your data
cp src/config/mapzen.{ts.sample,ts}
vi src/config/mapzen.ts

cp src/config/mapzen.{ts.sample,prod.ts}
vi src/config/mapzen.prod.ts

# Edit Firebase configuration files and update it with your data
cp src/config/firebase.{ts.sample,ts}
vi src/config/firebase.ts

cp src/config/firebase.{ts.sample,prod.ts}
vi src/config/firebase.prod.ts

# To populate firebase with the list of places and their coordinates:
# 1. Place your JSON/CSV data files at db/data folder following this structure:
#    [{
#      "name": "the name",
#      "address": "the address",
#      "zip": "00000",
#      "city": "the city",
#      "telephone": "999 999 999",
#      "email": "[email protected]",
#      "web": "www.the-web.com",
#      "group": "the group",
#      "type": "the type",
#      "latitude": "00.00000",
#      "longitude": "00.00000"
#     },
#     ...
#    ]

# 2. In your console at the application root execute the following script
#    (check out the examples in the usage information):
npm run db:populate

# 3. In firebase console go to the rules tab in your project view
#    and add the following rule in order to index and have better querys:
#    "coords": {
#      ".indexOn": ["g"]
#    }

# Run tests:
ng test

# Run the development server:
ng serve

If everything works, then you're ready to make changes.

Coding Standards

Style Guide

All code must follow the styles dictated by the official Angular Style Guide. As long as you use Angular CLI and don't skip the git hooks, you shouldn't need to worry about missing something.

Angular projects created using Angular CLI (like this) include Codelyzer as a dependency. Codelyzer will check your code against the Angular tslint rules every time you run ng lint or commit your changes.

Commit messages

Follow Angular Commit Message Guidelines to write your commit messages. To ease this task you can use Commitizen.

This repo is Commitizen-friendly and supports Commitizen out-of-the-box:

  • define an alias like alias nbin='PATH=$(npm bin):$PATH' as detailed in this Stackoverflow answer and
  • invoke it like this: nbin git-cz.

If you feel comfortable with global packages you can:

  1. install npm-run by running npm i -g npm-run and then invoke npm-run git-cz to commit your messages, or
  2. install commitizen by running npm i -g commitizen and commit your messages invoking git cz.

Contributing Guidelines

Acceptable Submissions

We will only accept submissions that:

  • report a bug in the source code.
  • propose a missing feature.

If you find a bug, please submit an issue or a Pull Request (PR) with your fix. If you miss a feature, you may:

  • craft it and submit it as a PR when it is small enough.
  • open an issue and outline your proposal for further discussion when it is a major one before you spend time working on it.

Submmitting an Issue

Before you submit an issue, please search the issue tracker, maybe an issue for your problem already exists and the discussion might inform you of workarounds readily available.

Before fixing a bug we need to reproduce and confirm it. Provide a minimal reproduction scenario using http://plnkr.co/. If plunker is not a suitable way to demonstrate the problem please create a standalone git repository demonstrating the problem.

Submitting a Pull Request

Before you submit your PR consider the following guidelines:

# Create a new branch:
git checkout -b my-branch staging

# Make your changes and try to make the tests pass.
# All the tests are executed on our Continuous Integration infrastructure
# and a PR could only be merged once the tests pass:
ng test --single-run
ng e2e

# If you can't or need help then commit what you have with `--no-verify`:
git add . && git commit --no-verify

# If you get things working add your changed files and commit with a message
# that follows our standards (see above). You'll notice that there are git hooks in place
# which will run testing, linting, etc. (unless you commit with `--no-verify`):
git add . && git cz

# Push your changes to your fork:
git push -u origin my-branch

# In GitHub, send a PR to `veinapp:staging`.
# Follow our feedback and iterate on the solution until we accept it.

# Rebase and squash your branch:
git rebase -i staging

# Add upstream/staging updates to your branch:
git fetch upstream
git rebase upstream/staging

# Push to your fork (this will update your PR):
git push -f

# Get merged! 🎉 🎊

After your PR is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:

# Update your staging with the latest upstream version:
git checkout staging -f
git pull --ff upstream staging

# Update your master with the latest upstream version:
git checkout master -f
git pull --ff upstream master

# Delete the remote branch on GitHub:
git push origin --delete my-branch

# Delete the local branch:
git branch -D my-branch

Resources