Commit 7993b4d8 authored by Craig Small's avatar Craig Small

docs: Updated documentation

Updated the documents with the following general changes:
* Replaced Gitorious with GitLab
* Moved translate stuff out of README
* Changed plain text to markdown (looks better on website)
parent 00313ef3
BUG REPORTS
===========
Please read this file before sending in a bug report or patch.
The following is information for reporting bugs. Please read
the file as well as the documentation for the relevant program
before posting. This document is more useful for advanced users
and the people that package for the distributions.
Also, PLEASE read the documentation first. 90% of the mail I get
complaining about procps-ng is due to the sender not having read the
documentation!
Also if you are an end-user of the programs and not the packager
and are using a distribution, check their bug tracker first,
you may find its a known bug already.
Where to send
=============
Send comments, bug reports, patches, etc., to procps@freelists.org
-------------
You can raise issues on the GitLab issues tracker which is
located at https://gitlab.com/procps-ng/procps/issues You
will need a GitLab login to do so.
Alternatively send comments, bug reports, patches, etc.
to the email list procps@freelists.org
What to send
============
It is much more useful to me if a program really crashes to recompile it
with make "CFLAGS=-ggdb -O", run it with "gdb prog" and "run" and send
me a stack trace ('bt' command). That said, any bug report is still
------------
It is much more useful to us if a program really crashes to recompile it
with make `CFLAGS=-ggdb -O`, run it with `gdb prog` and `run` and send
me a stack trace (`bt` command). That said, any bug report is still
better than none.
strace and ltrace output are very helpful:
strace -o output-file ps --blah
bzip2 output-file
> strace -o output-file ps --blah
> bzip2 output-file
I also like "ps --info" output, even if there isn't a ps problem.
The output of `ps --info` is often quite useful, even if the problem
is not with ps itself. A lot of the utilities use the same library.
Patches
=======
Merge Requests
--------------
Merge requests are fine to use and give a central place for
everyone involved to have a look. Merge requests are found
on GitLab at https://gitlab.com/procps-ng/procps/merge_requests
It is best to follow up your merge request with an email to
the list saying what you have done.
Patches
-------
While merge requests are preferred, patches are also welcome.
Get latest version of the source from upstream git.
git clone git://gitorious.org/procps/procps.git
> git clone git@gitlab.com:procps-ng/procps.git
and use 'git format-patch' format. It is fine to attach patches as
and use `git format-patch` format. It is fine to attach patches as
compressed tar balls. When you are about to send very large number
of patches consider setting up your personal clone, and send a pull
request.
git request-pull commit-id \
git://gitorious.org/~yourlogin/procps/your-clone.git
> git request-pull commit-id \
> git://gitorious.org/~yourlogin/procps/your-clone.git
Gitorious merge requests
========================
Prefer sending pull request to mail list. More people will notice a
change being proposed, making potential discussion to capture wider
point of view. Using gitorious merge reguest in combination mail
list announcement is fine.
Kernel-Dependent Patches
========================
If you send me patches which are specific to *running* with a particular
------------------------
If you send patches which are specific to *running* with a particular
kernel version of /proc, please condition them with the runtime determined
variable 'linux_version_code' from libproc/version.c. It is the same
number as the macro LINUX_VERSION_CODE for which the kernel /proc fs
variable `linux_version_code` from libproc/version.c. It is the same
number as the macro `LINUX_VERSION_CODE` for which the kernel /proc fs
code was compiled.
A macro is provide in libproc/version.h to construct the code from its
components, e.g.
if (linux_version_code < LINUX_VERSION(2,5,41))
/* blah blah blah */
A startup call to set_linux_version may also be necessary.
> if (linux_version_code < LINUX_VERSION(2,5,41))
> /* blah blah blah */
A startup call to `set_linux_version` may also be necessary.
Of course, if a bug is due to a change in kernel file formats, it would
be best to first try to generalize the parsing, since the code is then
more resilient against future change.
Code Structure
==============
--------------
A goal is to encapsulate *all* parsing dependent on /proc
file formats into the libproc library. If the API is general enough
it can hopefully stabilize and then /proc changes might only require
......
Translations
============
There is a three-step process for translating man pages. Most
of the work happens in the man-po directory.
> make -C man-po translate-templates
Creates the translation templates (the .pot files) for translators
to use as a base. These, along with the tar file, should be sent
to the tp-coorindator before release.
> make get-trans
rsyncs the latest translated (.po) files for both the programs and
man pages.
> make -C man-po translate-mans
This is also called in the dist-hook and is where the translation
magic happens. Take the original man page, the relevant .po file
and produce a translated man page in that language.
All of the man pages generated are found in
man-po/(LANG)/man(SECTION)/
Installation Instructions for procps
====================================
Depending on what format you are using to get these files, you
might need to run the `autogen.sh` program to create the
configure script. If you have a configure script already then
you might not need it.
A typical installation would go something like
> ./autogen.sh
> ./configure
> make
> make install
The configure script has a lot of options, so please have a read
of `configure --help` to see what they are and what they are used
for.
Testing
-------
procps has a series of test scripts (and more are welcome if they
are repeatable). You will need to install DejaGNU to run it and
it is simply:
> make check
COMPATIBILITY
This code is intended for use with Linux 2.6.xx, 3.x and
hopefully all future kernels.
INSTALLATION
If you are using git version of the project you need extra step.
./autogen.sh
After that, and everyone using .tar.xz version of procps-ng, can
do normal build. Read './configure --help' to select options for
your needs.
./configure
make
make install
If you have DejaGNU installed you can run optional test suite.
make check
HOW TO CONTRIBUTE
See Documentation/BUGS file.
PACKAGING
If you are a downstream maintainer (packager) for a Linux
distribution, please avoid causing troubles. This section
applies to you.
Avoid maintaining distribution specific patches. Send your
patches to upstream, where they are at least reviewed, if not
included.
Please forward bug reports. If your bug database is public and
busy enough to bother with, please make this known. Follow
Debian's lead in making the bug database easy to comment on via
email without need for an account.
For normal packages, ensure that you do not add debugging flags
to the CFLAGS variable.
TRANSLATING MAN PAGES
There is a three-step process for translating man pages. Most
of the work happens in the man-po directory.
make -C man-po translate-templates
Creates the translation templates (the .pot files) for translators
to use as a base. These, along with the tar file, should be sent
to the tp-coorindator before release.
make get-trans
rsyncs the latest translated (.po) files for both the programs and
man pages.
make -C man-po translate-mans
This is also called in the dist-hook and is where the translation
magic happens. Take the original man page, the relevant .po file
and produce a translated man page in that language.
All of the man pages generated are found in
man-po/(LANG)/man(SECTION)/
UPSTREAM & BUG REPORTS
procps-ng <procps@freelists.org>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment