README.md

   1 # Description
   2
   3 This is the Rails port, the [Ruby on Rails](http://rubyonrails.org/)
   4 application that powers [OpenStreetMap](http://www.openstreetmap.org).
   5
   6 The Rails port provides almost all the services which are available
   7 on the OpenStreetMap site, including:
   8
   9 * The web site itself, including the edit pages.
  10 * The editing [API](http://wiki.openstreetmap.org/wiki/API_v0.6).
  11 * Browse pages - a web front-end to the OpenStreetMap data.
  12 * The user system, including preferences, diary entries, friends and
  13   user-to-user messaging.
  14 * GPX uploads, browsing and API.
  15
  16 There are some non-Rails services which the site includes, for
  17 example; tiles, geocoding, GPX file loading. There are also some
  18 utilities which provide other services on the OpenStreetMap site,
  19 or improve its function, but are not integrated with the Rails
  20 port, for example; [Osmosis,](http://wiki.openstreetmap.org/wiki/Osmosis)
  21 [CGImap.](https://github.com/zerebubuth/openstreetmap-cgimap)
  22
  23 # License
  24
  25 This software is licensed under the [GNU General Public License 2.0](http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt),
  26 a copy of which can be found in the LICENSE file.
  27
  28 # Running it
  29
  30 You can find documentation on [how to setup and
  31 run](http://wiki.openstreetmap.org/wiki/The_Rails_Port) the software
  32 on the OpenStreetMap wiki.
  33
  34 # Hacking it
  35
  36 The canonical Git repository for this software is hosted at
  37 [git.openstreetmap.org](http://git.openstreetmap.org/?p=rails.git),
  38 but much of the development is done on GitHub and for most people
  39 [this repository on Github](https://github.com/openstreetmap/openstreetmap-website)
  40 will be a better place to start.
  41
  42 Anybody hacking on the code is welcome to join the
  43 [rails-dev](http://lists.openstreetmap.org/listinfo/rails-dev) mailing
  44 list where other people hacking on the code hang out and will be happy
  45 to help with any problems you may encounter. If you are looking for a
  46 project to help out with, please take a look at the list of
  47 [Top Ten Tasks](http://wiki.openstreetmap.org/wiki/Top_Ten_Tasks) that
  48 EWG maintains on the wiki.
  49
  50 There are also weekly IRC meetings, at 1800 GMT on Mondays in #osm-ewg on
  51 the OFTC network where questions can be asked and ideas discussed. For more
  52 information, please see [the EWG page]
  53 (http://www.osmfoundation.org/wiki/Engineering_Working_Group#Meetings). You can
  54 join the channel using your favourite IRC client or [irc.openstreetmap.org](http://irc.openstreetmap.org/).
  55
  56 ## Rails
  57
  58 If you're not already familiar with Ruby on Rails then it's probably
  59 worth having a look at [Rails Guides](http://guides.rubyonrails.org/) for an introduction.
  60
  61 While working with Rails you will probably find the [API documentation](http://api.rubyonrails.org/)
  62 helpful as a reference.
  63
  64 ## Coding style
  65
  66 When writing code it is generally a good idea to try and match your
  67 formatting to that of any existing code in the same file, or to other
  68 similar files if you are writing new code. Consistency of layout is
  69 far more important that the layout itself as it makes reading code
  70 much easier.
  71
  72 One golden rule of formatting -- please don't use tabs in your code
  73 as they will cause the file to be formatted differently for different
  74 people depending on how they have their editor configured.
  75
  76 ## Testing
  77
  78 Having a good suite of tests is very important to the stability and
  79 maintainability of any code base. The tests in the Rails port code are
  80 by no means complete, but they are extensive, and must continue to be
  81 so with any new functionality which is written. Tests are also useful
  82 in giving others confidence in the code you've written, and can
  83 greatly speed up the process of merging in new code.
  84
  85 When hacking, you should:
  86
  87 * Write new tests to cover the new functionality you've added.
  88 * Where appropriate, modify existing tests to reflect new or changed
  89 functionality.
  90 * Never comment out or remove a test just because it doesn't pass.
  91
  92 ## Comments
  93
  94 Sometimes it's not apparent from the code itself what it does, or,
  95 more importantly, **why** it does that. Good comments help your fellow
  96 developers to read the code and satisfy themselves that it's doing the
  97 right thing.
  98
  99 When hacking, you should:
 100
 101 * Comment your code - don't go overboard, but explain the bits which
 102 might be difficult to understand what the code does, why it does it
 103 and why it should be the way it is.
 104 * Check existing comments to ensure that they are not misleading.
 105
 106 ## Committing
 107
 108 When you submit patches, the project maintainer has to read them and
 109 understand them. This is difficult enough at the best of times, and
 110 misunderstanding patches can lead to them being more difficult to
 111 merge. To help with this, when submitting you should:
 112
 113 * Split up large patches into smaller units of functionality.
 114 * Keep your commit messages relevant to the changes in each individual
 115 unit.
 116
 117 When writing commit messages please try and stick to the same style as
 118 other commits, namely:
 119
 120 * A one line summary, starting with a capital and with no full stop.
 121 * A blank line.
 122 * Full description, as proper sentences with capitals and full stops.
 123
 124 For simple commits the one line summary is often enough and the body
 125 of the commit message can be left out.
 126
 127 ## Sending the patches
 128
 129 If you have forked on GitHub then the best way to submit your patches is to
 130 push your changes back to GitHub and then send a "pull request" on GitHub.
 131
 132 Otherwise you should either push your changes to a publicly visible git repository
 133 and send the details to the [rails-dev](http://lists.openstreetmap.org/listinfo/rails-dev)
 134 list or generate patches with `git format-patch` and send them to the
 135 [rails-dev](http://lists.openstreetmap.org/listinfo/rails-dev) list.
 136