From 92c847ef13cd721a37187c5878a05b54df48114a Mon Sep 17 00:00:00 2001 From: Jakub Filak Date: Sat, 20 Feb 2016 08:27:32 +0100 Subject: [PATCH] Add basic documentation Signed-off-by: Jakub Filak --- 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