Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Updated readme and contribution pages

  • Loading branch information...
commit 831e011cbe48b37cc01cbf5b449f394882257647 1 parent 63cbd45
Robin Hawkes robhawkes authored
Showing with 105 additions and 50 deletions.
  1. +57 −2 CONTRIBUTING.md
  2. +3 −15 LICENSE.md
  3. +45 −33 README.md
59 CONTRIBUTING.md
View
@@ -1,17 +1,72 @@
# Contributing to ViziCities
-[Like Ghost](https://github.com/TryGhost/Ghost/blob/master/CONTRIBUTING.md)
+The fact that you're looking at this page makes us incredibly happy, we need your help to make ViziCities as good as we know it can be.
+
+There are multiple ways you can help:
+
+* [Submitting bugs](#bug-reports)
+* [Requesting new features](#feature-requests)
+* [Requesting changes to existing features](#change-requests)
+* [Submitting your own code to the project](#working-on-vizicities)
## Raising issues
+The majority of contributions will come from bug reports and feature requests. Please read the following guidelines so things can happen as quickly and smoothly as possible.
+
+In general, make sure that you [search for existing issues](https://github.com/robhawkes/vizicities/issues) and discussions __before__ posting something new. Dealing with unnecessary duplication takes valuable time away from working on the project. If in doubt, [post something in the ViziCities Google Group](https://groups.google.com/forum/#!forum/vizicities).
+
### Bug reports
+Found something wrong with an existing feature? [Submit a bug report](https://github.com/robhawkes/vizicities/issues/new) so it can be fixed.
+
+If you follow the template below then you'll make everyone really happy.
+
+```
+Short and descriptive example bug report title
+
+### Issue Summary
+
+A summary of the issue and the browser/OS environment in which it occurs. If
+suitable, include the steps required to reproduce the bug.
+
+### Steps to Reproduce
+
+1. This is the first step
+2. This is the second step
+3. Further steps, etc.
+
+Any other information you want to share that is relevant to the issue being
+reported. Especially, why do you consider this to be a bug? What do you expect to happen instead?
+
+### Technical details:
+
+* ViziCities version: master (latest commit: c371147805bfaa448e973061be89c013ac867d15)
+* Client OS: Mac OS X 10.9.1
+* Node version: 0.10.0
+* Browser: Chrome 32.0.1700.77
+```
+
### Feature requests
+Got an idea for a new feature? Awesome! Double-checked to make sure it hasn't already been suggested? Even more awesome! Now you're ready to [submit a feature request](https://github.com/robhawkes/vizicities/issues/new). Make sure to provide as much detail as possible, focussing particularly on why this feature is needed (bonus points for example uses).
+
+If your idea isn't fully fleshed out yet then hold off on the feature request and [start a new topic in the ViziCities Google Group](https://groups.google.com/forum/#!forum/vizicities) — we'll put our heads together.
+
### Change requests
+Not happy with an existing feature, or think something could be tweaked? Check that it hasn't already been suggested and then [submit a change request](https://github.com/robhawkes/vizicities/issues/new).
+
+## Submitting code to ViziCities
+
+If you want to submit code to the project, perhaps on one of the new features, then you can do so [via a pull request](https://github.com/robhawkes/vizicities/pulls). We're pretty relaxed about the process for now, though we'll be implementing testing and procedure as the project matures.
+
+Bear in mind the following to help things go smoothly and quickly:
+
+* Pull requests that don't relate to [an existing issue](https://github.com/robhawkes/vizicities/issues) will be ignored or put to the back of the queue
+* Submitted code should be clean (no mess) and roughly follow the coding conventions of the project
+* Submitted code should not break an existing feature
-## Working on ViziCities
+If in doubt, [talk to us](https://github.com/robhawkes/vizicities#contact--community) and we'll help you through it.
## Contributor license agreement
18 LICENSE.md
View
@@ -4,20 +4,8 @@ The MIT License (MIT)
Copyright (c) 2014 - Robin Hawkes & Peter Smart
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
78 README.md
View
@@ -3,7 +3,7 @@ __Bringing cities to life using the power of open data and the Web__
![](http://f.cl.ly/items/0r0u0t1c2g1o3U1y3r2x/vizicities-combined-ssao.jpg)
-[ViziCities](http://vizicities.com) is a 3D city and data visualisation platform, powered by WebGL. It's sole purpose is to change the way you look at cities and the data contained within them. It is the brainchild of [Robin Hawkes](http://twitter.com/robhawkes) and [Peter Smart](http://twitter.com/petewsmart) — [get in touch](#contact--community) if you'd like to discuss the project with them in more detail.
+[ViziCities](http://vizicities.com) is a 3D city and data visualisation platform, powered by WebGL. Its purpose is to change the way you look at cities and the data contained within them. It is the brainchild of [Robin Hawkes](http://twitter.com/robhawkes) and [Peter Smart](http://twitter.com/petewsmart) — [get in touch](#contact--community) if you'd like to discuss the project with them in more detail.
### What does it do?
@@ -41,48 +41,72 @@ For more information you should start here:
## Future features
+* Dynamic city loading using OpenStreetMap data
* Tests and build status (TravisCI)
## Getting started
-ViziCities is at an incredibly early stage right now, but it's usable if you know what you're doing. The follow steps should get you up and running without too much trouble.
+ViziCities is at an incredibly early stage right now, but it's usable if you know what you're doing. The following steps should get you up and running without too much trouble.
### Building ViziCities
To start off, you'll need to build ViziCities and get an up-to-date JavaScript file.
-* Installing Grunt
-* Installing NPM packages
-* Building ViziCities with Grunt
-* Serving examples using Grunt
+#### [Install Node.js & NPM](http://nodejs.org/)
+```
+brew install node
+```
+#### [Install the Grunt CLI](http://gruntjs.com/getting-started)
+
+```
+npm install -g grunt-cli
+```
+
+#### Install the NPM packages
+```
+cd /path/to/vizicities
+npm install
+```
+
+#### Build ViziCities using Grunt
+```
+cd /path/to/vizicities
+grunt
+```
+
+#### Serve examples using Grunt
+```
+cd /path/to/vizicities
+grunt serve
+```
+
+Then open [http://127.0.0.1:8000/examples](http://127.0.0.1:8000/examples)
### Data formats
-Visualising geographic features lies at the core of ViziCities. To make sure features render correctly you'll need to [use the correct data formats](https://github.com/robhawkes/ViziCities/blob/master/DATA-FORMATTING.md).
+Visualising geographic features lies at the core of ViziCities. To make sure features render correctly you'll need to [use the correct data formats](https://github.com/robhawkes/vizicities/blob/master/DATA-FORMATTING.md).
### Using ViziCities
-* Using the built in example
-* Viewing your own city
+The idea is that you'll eventually be able to easily use your own data and visualise any city in the world. Until then, [a built in example](https://github.com/robhawkes/vizicities/tree/master/examples) has been provided to give you a taster of what ViziCities can do.
## Getting involved
-* Overview of contribution methods
-* Link to contribution details, [like Ghost](https://github.com/TryGhost/Ghost#getting-involved)
+ViziCities can't happen without your help. We need people to submit bugs, suggest features, share how they're using ViziCities, and contribute code to the project. Sound like you? [Check out exactly how to get involved](https://github.com/robhawkes/vizicities/blob/master/CONTRIBUTING.md).
## Contact & community
-* How to get in touch with us (email, Twitter)
-* Where to find ViziCities devs and community, [like Ghost](https://github.com/TryGhost/Ghost#community)
+Communicate with the ViziCities team via email ([hello@vizicities.com](mailto:hello@vizicities.com)) and Twitter ([@ViziCities](http://twitter.com/ViziCities)). All other discussion should happen in the [ViziCities Google Group](https://groups.google.com/forum/#!forum/vizicities) or [relevant GitHub issues page](https://github.com/robhawkes/vizicities/issues).
+
+## FAQ
-## Versioning
+### What happened to all the cool features I saw in the blog posts?
-* Potentially use [Ghost versioning text](https://github.com/TryGhost/Ghost#versioning)
-* Don't want anything too prescriptive just yet
+Over the past year [we've been producing experiments](http://rawkes.com/articles/vizicities-dev-diary-2) to prove that ViziCities is possible. These experiments, while working, were not robust and never intended for release. The version of ViziCities you see here is a solid foundation based on the lessons learnt from the previous experiments. It will eventually catch up with those experiments in regards to features.
## Copyright & license
@@ -91,20 +115,8 @@ The MIT License (MIT)
Copyright (c) 2014 - Robin Hawkes & Peter Smart
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Please sign in to comment.
Something went wrong with that request. Please try again.