Skip to content

Latest commit

 

History

History
112 lines (84 loc) · 4.96 KB

CONTRIBUTING.md

File metadata and controls

112 lines (84 loc) · 4.96 KB
Raw

How to contribute

We very much want the Air Quality Egg website to be great, and by this of course we mean beautiful to look at, but also more importantly, to implement the actual functionality that you, the community, want and need from this project.

To make this happen we need your help, so we want to make it as easy as possible for you (yes you!) to contribute changes that make things better for everyone.

There are a few guidelines that we need contributors to follow to make this process work in a way that we can keep on top of.

General discussion about the website

For general discussion about the features, functionality and look of the website, the place to start is probably the Air Quality Egg group. This is the place for chat about both the actual hardware Eggs and the website, and would be the best place to gather feedback from other users if you have either spotted an potential issue with the site, or would like to suggest some new functionality.

However the Google group definitely isn't the place to go if you'd like to actually contribute to the project, so to do that you need to be here on Github.

Getting started

To contribute to the project (we welcome either bug reports, or patches containing new features/functionality) you'll need to sign up for a free Github account.

Creating an issue

If you just want to raise a ticket containing a bug report or a feature request, then go to the issues page for the project here: https://github.com/xively/airqualityegg.com/issues, click New Issue and submit the issue you have identified.

If it's a bug report it would be most useful if you can give details of exactly the steps you took to find the bug, as it's critical that we are able to reproduce the bug in order to fix it.

If your issue is a feature request, I'd make sure you have discussed it in the Google group first of all to see if this is actually something that other users are interested in, and if that seems the case then we'd love to hear it.

Contributing changes

Raising issues is good and useful, but actually contributing changes that fix an issue is fantastic, so here's what you need to do.

Making changes

  • set up Git on your development machine: https://help.github.com/articles/set-up-git
  • fork the AQE repo into your account: https://help.github.com/articles/fork-a-repo
  • clone your forked repository onto your development machine
  • create a topic branch locally in which you'll make your changes

    • this will usually be the master branch

    • the command to create a branch would look something like:

      ```bash
git branch fix/my_contribution master
git checkout fix/my_contribution
```

    • you should never work directly on the master branch

  • make your changes within this branch, and commit these changes locally in logical chunks

    • try to make sure you commit messages are in the proper format:

      ```
Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the present tense: "Fix bug" and not "Fixed
bug."  This convention matches up with commit messages generated by
commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, preceded by a
  single space, with blank lines in between, but conventions vary here

- Use a hanging indent
```
  • make sure you add tests for any changes you make. We won't be able to accept your changes without tests.
  • please also make sure you run all the tests (bundle exec rake) to make sure your changes haven't broken something elsewhere.
  • document any changes in behaviour, including making sure the README is up to date.
  • try to make sure your topic branch only tackles a single issue. If you have multiple things you'd like change, please submit them separately.

Submitting changes

At this point you are waiting on us to review the changes, and if they are all good we will merge them and get them deployed to the production site. If we have any comments or suggestions then we will add them to your pull request, at which point you can then push updates to resolve all of these.