diff --git a/README.md b/README.md index b2b50dd98..fc41b4e7a 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,14 @@ -iD - friendly JavaScript editor for OpenStreetMap -================================================= +# iD - friendly JavaScript editor for OpenStreetMap -Basics ------- -* iD is a JavaScript-based [OpenStreetMap](http://www.openstreetmap.us/) editor. +## Basics + +* iD is a JavaScript-based [OpenStreetMap](http://www.openstreetmap.org/) editor. * It's intentionally simple. This is not a 90% editor - not even a 70% editor. It should let you do the most basic tasks while not breaking other people's data. Nothing more. (Same goes for the code, so go easy on the abstraction. :) ) -* Speaking of percentages, it's about 1% complete. -* The licence of iD is [WTFPL](http://sam.zoy.org/wtfpl/), though obviously, if you want to dual-license - any contributions that's cool. -Architecture ------------- +## Architecture * iD uses [d3js](http://d3js.org/) for graphics & managing databindings to the map. There's a tiny tiled-map core, but the majority of the action is in @@ -22,48 +17,55 @@ Architecture in Javascript that can be transformed by actions and serialized back into [changesets](http://wiki.openstreetmap.org/wiki/Changeset) -Getting started ---------------- -* Fork it and start playing! -* Read the [live docs](http://www.geowiki.com/docs/), generated from source every hour. +## Getting started + +* Fork this project. We eagerly accept pull requests. +* See [open issues in the issue tracker if you're looking for something to do](https://github.com/systemed/iD/issues?state=open) * All the code is in js/iD. +To run the code locally, just fork this project and run it from a local webserver. +With a Mac, you can enable Web Sharing and drop this in your website directory. -How it works ------------- -The code works similarly to [Potlatch 2](http://wiki.openstreetmap.org/wiki/Potlatch_2), -but with a bit less abstraction. So, we have: +If you have Python handy, just `cd` into `iD` and run -* Connection: stores, fetches and saves data. (iD/Connection.js) -* Entity (Node, Way, Relation): the data objects. (iD/Entity.js) -* EntityUI (NodeUI, WayUI): the rendered graphic elements. (iD/renderer/...) -* Map: the displayed map on which EntityUIs are rendered. (iD/renderer/Map.js) -* Controller: the heart of the app, which does its work via... -* ControllerState: the current UI mode. ControllerStates decide what to do in - response to mouse/keyboard events. (iD/controller/...) -* UndoableAction: the code to actually change the data, as fired by - ControllerStates. (iD/actions/...) + python -m SimpleHTTPServer -The UI is much more modal than Potlatch 2. In particular there's a "draw shape" -mode (the "Add road or shape" button) and an "edit object" mode. The directory -structure of iD/controller reflects this. +## How it works -As well as the [live docs](http://www.geowiki.com/docs/), you'll find -various notes and comments in the docs/ folder. Feel free to add to these. +The code inherits many elements from the [Potlatch 2](http://wiki.openstreetmap.org/wiki/Potlatch_2) +and [JOSM](http://josm.openstreetmap.de/) editors. +We store technical notes in [NOTES.md](https://github.com/systemed/iD/blob/master/NOTES.md). The +basic architecture is as follows: -Getting started ---------------- -Most of the interesting code is in the ControllerStates, which live in -iD/controller/. Each one corresponds to a UI mode (e.g. "drawing a way"). -Its EntityMouseEvent method takes the user's mouse event (e.g. "clicked on -a node"), carries out any actions, and returns the new ControllerState -(which might just be 'this', i.e. carry on with the current state). +* Map: vector rendering, panning behaviors & zoom/center state +* Tiles: receives map centers & draw tiles as a background for iD +* Connection: requests `/map` data from osm, parses this data and delivers it to the Graph +* Graph: stores a javascript object of `id -> osm object` +* History: stores multiple graphs which represent undo states +Relationships: -Coding tips ------------ +* Map has-a Tiles +* Map has-a Connection +* Map has-a History +* History has-many Graphs -Come on in, the water's lovely. More help? Ping RichardF on IRC -(irc.oftc.net, in #osm-dev or #osm), on the OSM mailing lists or at +## Coding tips + +This project has a few basic guidelines for incoming code. The cardinal rules are: + +1. Soft tabs only +2. Everything should pass [jshint](http://www.jshint.com/) without warning +3. Never write bugs + +(you can write bugs). If you need a style guide, [AirBNB has a decent one.](https://github.com/airbnb/javascript) + +Come on in, the water's lovely. More help? Ping RichardF or tmcw on IRC +(`irc.oftc.net`, in `#osm-dev` or `#osm`), on the OSM mailing lists or at richard@systemeD.net. + +## License + +iD is available under the [WTFPL](http://sam.zoy.org/wtfpl/), though obviously, if you want to dual-license +any contributions that's cool. It includes [d3js](http://d3js.org/), which BSD-licensed. diff --git a/screenshot.jpg b/screenshot.jpg new file mode 100644 index 000000000..03d04ea17 Binary files /dev/null and b/screenshot.jpg differ