From 0020bf80cda35ee0ce0ecf91023f3abcc1c4d26d 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