From bcd3805f22767a02cb9e3490a11de562fcb7bda5 Mon Sep 17 00:00:00 2001 From: Tom Hughes Date: Mon, 27 Feb 2012 18:21:00 +0000 Subject: [PATCH] Update README with more information on getting involved --- README.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.mkdn | 28 ----------- 2 files changed, 132 insertions(+), 28 deletions(-) create mode 100644 README.md delete mode 100644 README.mkdn diff --git a/README.md b/README.md new file mode 100644 index 000000000..edad66cc0 --- /dev/null +++ b/README.md @@ -0,0 +1,132 @@ +# Description + +This is the Rails port, the [Ruby on Rails](http://rubyonrails.org/) +application that powers [OpenStreetMap](http://www.openstreetmap.org). + +The Rails port provides almost all the services which are available +on the OpenStreetMap site, including: + +* The web site itself, including the edit pages. +* The editing [API](http://wiki.openstreetmap.org/wiki/API_v0.6). +* Browse pages - a web front-end to the OpenStreetMap data. +* The user system, including preferences, diary entries, friends and + user-to-user messaging. +* GPX uploads, browsing and API. + +There are some non-Rails services which the site includes, for +example; tiles, geocoding, GPX file loading. There are also some +utilities which provide other services on the OpenStreetMap site, +or improve its function, but are not integrated with the Rails +port, for example; Osmosis, CGImap. + +# License + +This software is licensed under the [GNU General Public License 2.0](http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt), +a copy of which can be found in the LICENSE file. + +# Running it + +You can find documentation on [how to setup and +run](http://wiki.openstreetmap.org/wiki/The_Rails_Port) the software +on the OpenStreetMap wiki. + +# Hacking it + +The canonical Git repository for this software is hosted at +[git.openstreetmap.org](http://git.openstreetmap.org/?p=rails.git), +but much of the development is done on GitHub and for most people +[this repository on Github](https://github.com/openstreetmap/openstreetmap-website) +will be a better place to start. + +Anybody hacking on the code is welcome to join the +[rails-dev](http://lists.openstreetmap.org/listinfo/rails-dev) mailing +list where other people hacking on the code hang out and will be happy +to help with any problems you may encounter. + +There are also weekly IRC meetings, at 1800 GMT on Mondays in #osm-ewg on +the OFTC network where questions can be asked and ideas discussed. For more +information, please see [the EWG page] +(http://www.osmfoundation.org/wiki/Engineering_Working_Group#Meetings). You can +join the channel using your favourite IRC client or [irc.openstreetmap.org](http://irc.openstreetmap.org/). + +## Rails + +If you're not already familiar with Ruby on Rails then it's probably +worth having a look at [Rails Guides](http://guides.rubyonrails.org/) for an introduction. + +While working with Rails you will probably find the [API documentation](http://api.rubyonrails.org/) +helpful as a reference. + +## Coding style + +When writing code it is generally a good idea to try and match your +formatting to hat of any existing code in the same file, or to other +similar files if you are writing new code. Consistency of layout is +far more important that the layout itself as it makes reading code +much easier. + +One golden rule of formatting -- please don't use tabs in your code +as they will cause the file to be formatted differently for different +people depending on how they have their editor configured. + +## Testing + +Having a good suite of tests is very important to the stability and +maintainability of any code base. The tests in the Rails port code are +by no means complete, but they are extensive, and must continue to be +so with any new functionality which is written. Tests are also useful +in giving others confidence in the code you've written, and can +greatly speed up the process of merging in new code. + +When hacking, you should: + +* Write new tests to cover the new functionality you've added. +* Where appropriate, modify existing tests to reflect new or changed +functionality. +* Never comment out or remove a test just because it doesn't pass. + +## Comments + +Sometimes it's not apparent from the code itself what it does, or, +more importantly, **why** it does that. Good comments help your fellow +developers to read the code and satisfy themselves that it's doing the +right thing. + +When hacking, you should: + +* Comment your code - don't go overboard, but explain the bits which +might be difficult to understand what the code does, why it does it +and why it should be the way it is. +* Check existing comments to ensure that they are not misleading. + +## Committing + +When you submit patches, the project maintainer has to read them and +understand them. This is difficult enough at the best of times, and +misunderstanding patches can lead to them being more difficult to +merge. To help wit this, when submitting you should: + +* Split up large patches into smaller units of functionality. +* Keep your commit messages relevant to the changes in each individual +unit. + +When writing commit messages please try and stick to the same style as +other commits, namely: + +* A one line summary, starting with a capital and with no full stop. +* A blank line. +* Full description, as proper sentences with capitals and full stops. + +For simple commits the one line summary is often enough and the body +of the commit message can be left out. + +## Sending the patches + +If you have forked on GitHub then the best way to submit your patches is to +push your changes back to GitHub and then send a "pull request" on GitHub. + +Otherwise you should either push your changes to a publicly visible git repository +and send the details to the [rails-dev](http://lists.openstreetmap.org/listinfo/rails-dev) +list or generate patches with `git format-patch` and send them to the +[rails-dev](http://lists.openstreetmap.org/listinfo/rails-dev) list. + diff --git a/README.mkdn b/README.mkdn deleted file mode 100644 index 5c952766f..000000000 --- a/README.mkdn +++ /dev/null @@ -1,28 +0,0 @@ -# Description - -This is the Rails port. The Ruby on Rails application that powers -http://www.openstreetmap.org. - -# Running it - -You can find documentation on how to setup and run the software on the -OpenStreetMap wiki: - -* http://wiki.openstreetmap.org/wiki/The_Rails_Port - -# Hacking it - -The canonnical Git repository for this software is hosted at -git.openstreetmap.org: - -* http://git.openstreetmap.org/?p=rails.git - -See commiting to the rails port on the wiki for getting your patches -integrated: - -* http://wiki.openstreetmap.org/wiki/Committing_to_the_rails_port - -## License - -This software is licensed under the GNU General Public License 2.0. -See included LICENSE file for details. -- 2.43.2