Bug 1285959 - Provide a better README file for users coming to Bugzilla via the github repo

2 files changed, 93 insertions, 54 deletions

diff --git a/README b/README
deleted file mode 100644
index e68afd8e4..000000000
--- a/README
+++ /dev/null
@@ -1,54 +0,0 @@
-Bugzilla
-========
-
-Bugzilla is free and open source web-based bug-tracking software that is
-developed by an active group of volunteers in the Mozilla community, and used
-by thousands of projects and companies around the world. It can be installed on
-Linux and other flavors of Unix, Windows or Mac OS X.
-
-You can try Bugzilla out using our testing installation:
-https://landfill.bugzilla.org/bugzilla-tip/
-
-Documentation
-=============
-
-Bugzilla's comprehensive documentation, including installation instructions,
-can be found here:
-http://www.bugzilla.org/docs/
-
-Reporting Bugs
-==============
-
-Report bugs here:
-https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla
-
-(Please do not file test bugs in this installation of Bugzilla.)
-
-Mailing Lists
-=============
-
-Development:
-https://www.mozilla.org/en-US/about/forums/#dev-apps-bugzilla
-
-Support:
-https://www.mozilla.org/en-US/about/forums/#support-bugzilla
-
-IRC
-===
-
-You can often find Bugzilla developers on IRC:
-irc://irc.mozilla.org/bugzilla
-
-License
-=======
-
-This Source Code Form is subject to the terms of the Mozilla Public
-License, v. 2.0. If a copy of the MPL was not distributed with this
-file, You can obtain one at http://mozilla.org/MPL/2.0/.
-
-This Source Code Form is "Incompatible With Secondary Licenses", as
-defined by the Mozilla Public License, v. 2.0.
-
-However, this is all only relevant to you if you want to modify the code and
-redistribute it. As with all open source software, there are no restrictions
-on running it, or on modifying it for your own purposes.
diff --git a/README.rst b/README.rst
new file mode 100644
index 000000000..458066b78
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,93 @@
+============================================
+Bugzilla: A Free and Open-Source Bug Tracker
+============================================
+
+Bugzilla is free and open source web-based bug-tracking software that is
+developed by an active group of volunteers in the Mozilla community, and
+used by thousands of projects and companies around the world.
+
+----
+|homepage| |documentation| |irc| |docker_pulls| |license|
+----
+
+Usage
+=====
+
+Bugzilla requires Perl 5.14 (or newer) and tools to compile and install perl
+modules, including make(1) and a C compiler.
+
+For Developers
+--------------
+
+If you have the `cpanm <https://github.com/miyagawa/cpanminus#installation>`__ script in your $PATH,
+Bugzilla can be up and running in three commands.
+
+.. code-block:: bash
+
+    perl checksetup.pl --cpanm
+
+At this point ``localconfig`` can be edited to specify database connection parameters. If SQLite is acceptable,
+no edits are required.
+
+The checksetup.pl script should be run again to set up the database schema.
+
+.. code-block:: bash
+
+    perl checksetup.pl
+
+It will ask for some details, such as login name and password.
+
+Finally, a webserver can be started by the following:
+
+.. code-block:: bash
+
+    perl -Ilocal/lib/perl5 local/bin/plackup
+
+Navigate to http://localhost:5000/ and login with the username and password provided earlier to checksetup.
+Remember to set the urlbase on http://localhost:5000/editparams.cgi. "http://localhost:5000" will probably suffice.
+
+For Operations
+--------------
+
+For a production setup, see the `installation guide <http://bugzilla.readthedocs.io/en/latest/installing/index.html>`__
+
+Links and Other Resources
+=========================
+
+-  Join irc.mozilla.org #bugzilla (or use the `Bugzilla IRC Gateway <http://landfill.bugzilla.org/irc/>`__)
+-  Ask questions on the `Support <https://www.mozilla.org/en-US/about/forums/#support-bugzilla>`__
+   mailing list
+- `Report Bugs <https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla>`__
+   (Please do not file test bugs in this installation of Bugzilla.)
+-  Contributing a patch? Join us from 11:00 to 12:00 US/Eastern every Thursday in Bugzilla IRC Channel for `Contributor Office Hours <http://goo.gl/2Wz8x6>`__.
+-  If you haven't already, subscribe to the `Development <https://www.mozilla.org/en-US/about/forums/#dev-apps-bugzilla>`__
+   mailing list.
+
+License
+-------
+
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+This Source Code Form is "Incompatible With Secondary Licenses", as
+defined by the Mozilla Public License, v. 2.0.
+
+However, this is all only relevant to you if you want to modify the code and
+redistribute it. As with all open source software, there are no restrictions
+on running it, or on modifying it for your own purposes.
+
+.. |homepage| image:: https://img.shields.io/badge/home-bugzilla.org-blue.svg
+   :target: http://bugzilla.org
+.. |docker_pulls| image:: https://img.shields.io/docker/pulls/dklawren/docker-bugzilla.svg
+   :target: https://hub.docker.com/r/dklawren/docker-bugzilla/
+   :alt: docker pulls
+.. |documentation| image:: https://readthedocs.org/projects/bugzilla/badge/?version=latest
+   :target: http://bugzilla.readthedocs.io/en/latest/
+   :alt: Documentation
+.. |irc| image:: https://img.shields.io/badge/chat-%23bugzilla-blue.svg
+   :target: http://landfill.bugzilla.org/irc/
+   :alt: Chat with us on IRC
+.. |license| image:: https://img.shields.io/github/license/bugzilla/bugzilla.svg?maxAge=2592000
+   :target: #license
+   :alt: License