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