From 92c847ef13cd721a37187c5878a05b54df48114a Mon Sep 17 00:00:00 2001
From: Jakub Filak <jfilak@redhat.com>
Date: Sat, 20 Feb 2016 08:27:32 +0100
Subject: [PATCH] Add basic documentation
Signed-off-by: Jakub Filak <jfilak@redhat.com>
---
CONTRIBUTING.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
INSTALL | 7 -----
INSTALL.md | 56 ++++++++++++++++++++++++++++++++++
Makefile.am | 2 ++
README | 11 -------
README.md | 48 +++++++++++++++++++++++++++++
6 files changed, 200 insertions(+), 18 deletions(-)
create mode 100644 CONTRIBUTING.md
delete mode 100644 INSTALL
create mode 100644 INSTALL.md
delete mode 100644 README
create mode 100644 README.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..4b27138
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,94 @@
+# Contributing to ABRT
+
+Adopted from http://www.contribution-guide.org/
+
+BSD, Copyright (c) 2015 Jeff Forcier
+
+## Submitting bugs
+
+### Due diligence
+
+Before submitting a bug, please do the following:
+
+* Perform **basic troubleshooting** steps:
+
+ * **Make sure you're on the latest version.** If you're not on the most
+ recent version, your problem may have been solved already! Upgrading is
+ always the best first step.
+ * **Try older versions.** If you're already *on* the latest release, try
+ rolling back a few minor versions (e.g. if on 1.7, try 1.5 or 1.6) and
+ see if the problem goes away. This will help the devs narrow down when
+ the problem first arose in the commit log.
+ * **Try switching up dependency versions.** If the software in question has
+ dependencies (other libraries, etc) try upgrading/downgrading those as
+ well.
+
+* **Search the project's bug/issue tracker** to make sure it's not a known issue.
+* If you don't find a pre-existing issue, consider **checking with the mailing
+ list and/or IRC channel** in case the problem is non-bug-related.
+* Consult [README.md](README.md) for links to bugtracker, mailinglist or IRC.
+
+### What to put in your bug report
+
+Make sure your report gets the attention it deserves: bug reports with missing
+information may be ignored or punted back to you, delaying a fix. The below
+constitutes a bare minimum; more info is almost always better:
+
+* **What version of the core programming language interpreter/compiler are you
+ using?** For example, if it's a Python project, are you using Python 2.7.3?
+ Python 3.3.1? PyPy 2.0?
+* **What operating system are you on?** Make sure to include release and distribution.
+* **Which version or versions of the software are you using?** Ideally, you
+ followed the advice above and have ruled out (or verified that the problem
+ exists in) a few different versions.
+* **How can the developers recreate the bug on their end?** If possible,
+ include a copy of your code, the command you used to invoke it, and the full
+ output of your run (if applicable.)
+
+ * A common tactic is to pare down your code until a simple (but still
+ bug-causing) "base case" remains. Not only can this help you identify
+ problems which aren't real bugs, but it means the developer can get to
+ fixing the bug faster.
+
+
+## Contributing changes
+
+It would be the best if you could discuss your plans with us on #abrt or on our
+mailinig list crash-catcher@lists.fedorahosted.org before you spent too much
+energy and time.
+
+Before contributing, please, make yourself familiar with git. You can [try git
+online](https://try.github.io/). Things would be easier for all of us if you do
+your changes on a branch. Use a single commit for every logical reviewable
+change, without unrelated modifications (that will help us if need to revert a
+particular commit). Please avoid adding commits fixing your previous
+commits, do amend or rebase instead.
+
+Every commit must have either comprehensive commit message saying what is being
+changed and why or a link (an issue number on Github) to a bug report where
+this information is available. It is also useful to include notes about
+negative decisions - i.e. why you decided to not do particular things. Please
+bare in mind that other developers might not understand what the original
+problem was.
+
+### Full example
+
+Here's an example workflow for a project `abrt` hosted on Github
+Your username is `yourname` and you're submitting a basic bugfix or feature.
+
+* Hit 'fork' on Github, creating e.g. `yourname/abrt`.
+* `git clone git@github.com:yourname/abrt`
+* `cd abrt`
+* `git checkout -b foo_the_bars` to create new local branch named foo_the_bars
+* Hack, hack, hack
+* Run `make check`
+* `git status`
+* `git add`
+* `git commit -s -m "Foo the bars"`
+* `git push -u origin HEAD` to create foo_the_bars branch in your fork
+* Visit your fork at Github and click handy "Pull request" button.
+* In the description field, write down issue number (if submitting code fixing
+ an existing issue) or describe the issue + your fix (if submitting a wholly
+ new bugfix).
+* Hit 'submit'! And please be patient - the maintainers will get to you when
+ they can.
diff --git a/INSTALL b/INSTALL
deleted file mode 100644
index 799a4a6..0000000
--- a/INSTALL
+++ /dev/null
@@ -1,7 +0,0 @@
-How to install
-==============
-
-1. autogen.sh
-2. ./configure
-3. make
-4. make install
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..96d42c4
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,56 @@
+# How to install
+
+### Development dependencies
+
+Build dependencies can be listed by:
+
+ $ ./autogen.sh sysdeps
+
+or installed by:
+
+ $ ./autogen.sh sysdeps --install
+
+The dependency installer gets the data from [the rpm spec file](abrt.spec.in)
+
+### Building from sources
+
+When you have all dependencies installed run the following commands:
+
+ $ ./autogen.sh --prefix=/usr \
+ --sysconfdir=/etc \
+ --localstatedir=/var \
+ --sharedstatedir=/var/lib
+
+ $ make
+
+or if you want to debug ABRT run:
+
+ $ CFLAGS="-g -g3 -ggdb -ggdb3 -O0" ./autogen.sh --prefix=/usr \
+ --sysconfdir=/etc \
+ --localstatedir=/var \
+ --sharedstatedir=/var/lib \
+ --enable-debug
+
+ $ make
+
+### Checking
+
+ABRT uses [Autotest](http://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Using-Autotest.html)
+to validate source codes. Run the test by:
+
+ $ make check
+
+If you want to search for memory issues, build ABRT with debug options and then
+run:
+
+ $ make maintainer-check
+
+### Installing
+
+If you need an rpm package, run:
+
+ $ make rpm
+
+otherwise run:
+
+ $ make install
diff --git a/Makefile.am b/Makefile.am
index 01b8a97..e528c93 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -36,6 +36,8 @@ EXTRA_DIST = doc/coding-style abrt.spec.in abrt.pc.in \
abrt-version asciidoc.conf init-scripts/* $(TESTSUITE_FILES) \
augeas/test_abrt.aug
+dist_doc_DATA = README.md
+
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = abrt.pc
diff --git a/README b/README
deleted file mode 100644
index 26cbbcb..0000000
--- a/README
+++ /dev/null
@@ -1,11 +0,0 @@
-These sources are in early stages. They are changing every day :-)...
-Anyway, patches are welcome.
-
-** Using Valgrind
-
-When running ABRT under memcheck, GLib's environment variables should
-be set to turn off glib's memory optimization, so valgrind is not
-confused:
-
-G_SLICE=always-malloc G_DEBUG=gc-friendly valgrind --tool=memcheck \
- --leak-check=full abrtd -dvvv
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e58a499
--- /dev/null
+++ b/README.md
@@ -0,0 +1,48 @@
+# ABRT
+
+**A set of tools to help users detect and report application crashes.**
+
+### About
+
+Its main purpose is to ease the process of reporting an issue and finding a
+solution.
+
+The solution in this context might be a bugzilla ticket, knowledge base article
+or a suggestion to update a package to a version containing a fix.
+
+### Documentation
+
+Every ABRT program and configuration file has a man page describing it. It is
+also possible to [read the ABRT documentation](http://abrt.readthedocs.org/)
+online. For contributors and developers, there are also [wiki
+pages](https://github.com/abrt/abrt/wiki) describing some topics to deeper
+technical details.
+
+### Development
+
+ * IRC Channel: #abrt on FreeNode
+ * [Mailing List](https://lists.fedorahosted.org/admin/lists/crash-catcher.lists.fedorahosted.org/)
+ * [Bug Reports and RFEs](https://github.com/abrt/abrt/issues)
+ * [Contributing to ABRT](CONTRIBUTING.md)
+ * [Install and run ABRT](INSTALL.md)
+
+
+### Running
+
+ABRT consist of several services and many small utilities. While The utilities
+can be successfully run from the source directories after build, the services
+often uses the utilities to do actions and expect the utilities installed in
+the system directories. Hence to run the services, it is recommended to install
+ABRT first and run them as system services. The instructions how to build
+and install ABRT can be found in [INSTALL.md](INSTALL.md)
+
+### Technologies
+
+* [libreport](https://github.com/abrt/libreport) - problem data format, reporting
+* [satyr](https://github.com/abrt/satyr) - backtrace processing, micro-reports
+* [Python3](https://www.python.org/)
+* [GLib2](https://developer.gnome.org/glib/)
+* [Gtk3](https://developer.gnome.org/gtk3)
+* [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/)
+* [SELinux](https://github.com/SELinuxProject/selinux/wiki)
+* [systemd](https://www.freedesktop.org/wiki/Software/systemd/)
--
2.5.5