README.developers

This file contains information for libfaketime developers and contributors.


GENERAL
=======

Starting with libfaketime v0.9.5, development and issue handling is
completely done via Github:

	https://github.com/wolfcw/libfaketime

- Official releases are tagged.

- Code contributions and bugfixes should be submitted to and then merged into
  the "development" branch, which is considered unstable and may contain code
  that is not yet fully tested.

- The "master" branch is updated with tested code only; it is ensured that
  it compiles and works cleanly at least on current Linux and macOS systems.

Code contributions are highly welcome, preferably via pull requests on Github.

Please have a look at issues labelled as "help wanted" in the Github issue
tracker. If you are interested in contributing to libfaketime, helping with
these issues is not only much appreciated, but also a good way to familiarize
yourself with the overall codebase.


CODE STYLE
==========

Please try to stick to the following code formatting style guidelines:

- No tabs, only spaces for indentation.
- Avoid trailing whitespace.
- Indentation is 2 spaces for each level.
- Opening and closing curly brackets have to be on lines of their own.
- Use under_score_names for function and variable names; avoid using camelCase.
- // and /*...*/ style comments may and shall be used.

Example:

/* This function will do nothing */
void do_nothing(int how_often)
{
  int counter;
  for (counter = 0; counter < how_often; counter++)
  {
    counter = counter; // our do-nothing algorithm
  }
}

- Use -DDEBUG and #ifdef DEBUG for development and testing. Avoid printing to
  stdout or stderr outside "#ifdef DEBUG"; if it is necessary to inform the
  user a run-time, prefix your output with "libfaketime" or make otherwise sure
  that the user knows where the message is coming from.

- If you add new functions to libfaketime.c, try placing them somewhere
  where they fit will: Usually, functions are grouped by functionality
  (e.g., all functions related to faking file timestamps). If that's not
  possible, group them by contributor, or document your placement strategy
  in the commit message.


DEVELOPMENT, BUILDING, AND TESTING
==================================

- Don't break existing behaviour. Backward compatibility matters (unless
  the modification fixes bugs :-)).

- Add tests for new features. Extend test/timetest.c appropriately and
  try to use the functional testing framework wherever possible.

- Compiler and linker warnings are treated as errors and not acceptable.

- If you cannot test the code on both Linux and macOS yourself, please
  let us know and consider wrapping your code in #ifdef / #ifndef __APPLE__
  statements.


DOCUMENTATION
=============

For anything more than small bugfixes, please update the user documentation
and credits appropriately:

- The NEWS file should mention the change and your credits.
- The README and README.OSX files should be updated whenever functionality
  is added or modified.
- The manpage man/faketime.1 should be updated when the wrapper application
  is modified.

For credits, please either mention your real name, your Github username, or
your email address.

In your own interest, please be verbose on user documentation and comments
in the source code. Users will not know about new features unless they are
documented. Other authors and maintainers will need to understand your code
easily.


RELEASES
========

Official new releases are created whenever a significant amount of changes
(bugfixes or new functionality) has piled up; on average, there is one new
official release per 1-2 years. Users who need to stick to the bleeding edge
are supposed to use the current state of the "master" branch at any time.

libfaketime maintainers for several Linux distributions are informed about
release candidates and new releases by email. Contact wolfcw on Github if
you are interested in receiving notifications, or use Github functionality
to get informed about updates.