=======================================================
             libfaketime, version 0.9.6 (June 2014)
        (previously also known as FakeTime Preload Library)
      =======================================================


Content of this file:
---------------------

1. Introduction
2. Compatibility issues
3. Installation
4. Usage
   a) Basics
   b) Using absolute dates
   c) Using 'start at' dates
   d) Using offsets for relative dates
   e) Advanced features and caveats
   f) Faking the date and time system-wide
   g) Using the "faketime" wrapper script
   h) "Limiting" libfaketime based on elapsed time or number of calls
   i) "Limiting" libfaketime per process
   j) Spawning an external process
   k) Saving timestamps to file, loading them from file
5. License
6. Contact



1. Introduction
---------------

libfaketime intercepts various system calls which programs use to
retrieve the current date and time. It can then report faked dates and times
(as specified by you, the user) to these programs. This means you can modify
the system time a program sees without having to change the time system-wide.

libfaketime allows you to specify both absolute dates (e.g., 01/01/2004) and
relative dates (e.g., 10 days ago).

libfaketime might be used for various purposes, for example

- running legacy software with y2k bugs
- testing software for year-2038 compliance
- debugging time-related issues, such as expired SSL certificates
- running software which ceases to run outside a certain timeframe
- using different system-wide date and time settings, e.g., on OpenVZ-
  based virtual machines running on the same host
- deterministic build processes.



2. Compatibility issues
-----------------------

* libfaketime has been designed on and for Linux, but is supposed and has been
  reported to work on other *NIXes as well, including Mac OS X.

* libfaketime uses the library preload mechanism and thus cannot work with
  statically linked binaries or binaries that have the setuid-flag set (e.g.,
  suidroot programs like "ping" or "passwd"). Please see you system linker's
  manpage for further details (man ld).

* As of version 0.7, support has been added for use in a pthreads environment. A
  separate library is built (libfaketimeMT.so.1) which contains the pthread
  synchronization calls. This library also single-threads calls through the
  time() intercept, because several variables are statically cached by the
  library and could cause issues when accessed without synchronization. However,
  the performance penalty for this might be an issue for some applications. If
  this is the case, you can try using an unsynchronized time() intercept by
  removing the -DPTHREAD_SINGLETHREADED_TIME from the Makefile and rebuilding
  libfaketimeMT.so.1 . Thanks to David North, TDI!

* If and only if you want to run Java programs with faked times in the future
  (not in the past) on Linux, you also should set the environment variable
  LD_ASSUME_KERNEL=2.4.19 before running the appropriate "java" command. This
  fixes an occasional bug where Java locks up at exiting. Again, this is only
  required for Java with faked times in the future. Thanks to Jamie Cameron for
  reporting this issue and finding a workaround!

* libfaketime will eventually be bypassed by applications that dynamically load
  system libraries, such as librt, explicitly themselves instead of relying on
  the linker to do so at application start time. libfaketime will not work with
  those applications unless you can modify them.

* Applications can explicitly be designed to prevent libfaketime from working,
  e.g., by checking whether certain environment variables are set or whether
  libfaketime-specific files are present.



3. Installation
---------------

Running "make" should compile both library versions and a test program, which
it then also executes.

If the test works fine, you should copy the libfaketime libraries
(libfaketime.so.1, and libfaketimeMT.so.1) to the place you want them in.
Running "make install" will attempt to place them in /usr/local/lib/faketime
and will install the wrapper shell script "faketime" in /usr/local/bin, both of
which most likely will require root privileges; however, from a technical point
of view, there is no necessity for a system-wide installation, so you can use
libfaketime also on machines where you do not have root privileges. You may want
to adjust the PREFIX variable in the Makefiles accordingly.

By default, the Makefile compiles/links libfaketime for your default system
architecture. If you need to build, e.g., 32-bit files on a 64-bit platform,
please see the notes about CFLAGS and LDFLAGS in src/Makefile.

Since version 0.6, system calls to file timestamps are also intercepted,
thanks to a contribution by Philipp Hachtmann. This is especially useful in
combination with relative time offsets as explained in section 4d) below, if a
program writes and reads files whose timestamps also shall be faked. If you do
not need this feature or if it confuses the application you want to use FTPL
with, define the environment variable NO_FAKE_STAT, and the intercepted stat
calls will be passed through unaltered.

On OS X, it is necessary to compile differently, due to the different
behavior dyld has. Use the Makefile provided to compile
libfaketime.1.dylib. Additionally, instead of using LD_PRELOAD,
the variable DYLD_INSERT_LIBRARIES should be set to the path to
libfaketime.1.dylib, and the variable DYLD_FORCE_FLAT_NAMESPACE should be
set (to anything). Mac OS X users should read README.OSX for additional
details.



4. Usage
--------

4a) Usage basics
----------------

Using libfaketime on a program of your choice consists of two steps:

1. Making sure libfaketime gets loaded by the system's linker.
2. Specify the faked time.


As an example, we want the "date" command to report our faked time. To do so,
we could use the following command line on Linux:

user@host> date
Tue Nov 23 12:01:05 CEST 2007

user@host> LD_PRELOAD=/usr/local/lib/libfaketime.so.1 FAKETIME="-15d" date
Mon Nov  8 12:01:12 CEST 2007


The basic way of running any command/program with libfaketime enabled is to
make sure the environment variable LD_PRELOAD contains the path and
filename of the libfaketime library. This can either be done by setting it once
beforehand:

export LD_PRELOAD=/path/to/libfaketime.so.1
(now run any command you want)


Or it can be done by specifying it on the command line itself:

LD_PRELOAD=/path/to/libfaketime.so.1 your_command_here

(These examples are for the bash shell; how environment variables are set may
vary on your system.)

On Linux, library search paths can be set as part of the linker configuration.
LD_PRELOAD then also works with relative paths. For example, when libfaketime.so.1
is installed as /path/to/libfaketime.so.1, you can add /path/to to an appropriate
linker configuration file, e.g., /etc/ld.so.conf.d/local.conf and then run
the "ldconfig" command. Afterwards, using LD_PRELOAD=libfaketime.so.1 suffices.

However, also the faked time should be specified; otherwise, libfaketime
will be loaded, but just report the real system time. There are three
ways to specify the faked time:

a) By setting the environment variable FAKETIME.
b) By using the file given in the environment variable FAKETIME_TIMESTAMP_FILE
c) By using the file .faketimerc in your home directory.
d) By using the file /etc/faketimerc for a system-wide default.

If you want to use b) c) or d), $HOME/.faketimerc or /etc/faketimerc consist of
only one line of text with exactly the same content as the FAKETIME environment
variable, which is described below. Note that /etc/faketimerc will only be used
if there is no $HOME/.faketimerc nor FAKETIME_TIMESTAMP_FILE file exists, and
the FAKETIME environment variable always has priority over the files.


4b) Using absolute dates
------------------------

The format which _must_ be used for _absolute_ dates is "YYYY-MM-DD hh:mm:ss".
For example, the 24th of December, 2002, 8:30 PM would have to be specified as
FAKETIME="2002-12-24 20:30:00".


4c) Using 'start at' dates
--------------------------

(Thanks to a major contribution by David North, TDI in version 0.7)

The format which _must_ be used for _start_at_ dates is "@YYYY-MM-DD hh:mm:ss".
For example, the 24th of December, 2002, 8:30 PM would have to be specified as
FAKETIME="@2002-12-24 20:30:00".

The absolute dates described in 4b simulate a STOPPED system clock at the
specified absolute time. The 'start at' format allows a 'relative' clock
operation as described below in section 4d, but using a 'start at' time
instead of an offset time.


4d) Using offsets for relative dates
------------------------------------

Relative date offsets can be positive or negative, thus what you put into
FAKETIME _must_ either start with a + or a -, followed by a number, and
optionally followed by a multiplier:

- by default, the offset you specify is in seconds. Example:

  export FAKETIME="-120" will set the faked time 2 minutes (120 seconds) behind
  the real time.

- the multipliers "m", "h", "d" and "y" can be used to specify the offset in
  minutes, hours, days and years (365 days each), respectively. Examples:

  export FAKETIME="-10m" sets the faked time 10 minutes behind the real time.
  export FAKETIME="+14d" sets the faked time to 14 days in the future.


You now should understand the complete example we've used before:

LD_PRELOAD=/usr/local/lib/libfaketime.so.1 FAKETIME="-15d" date

This command line makes sure FTPL gets loaded and sets the faked time to
15 days in the past.

Moreno Baricevic has contributed support for the FAKETIME_FMT environment
variable, which allows you to optionally set the strptime() format:

Some simple examples:
LD_PRELOAD=./libfaketime.so.1 FAKETIME_FMT=%s FAKETIME="`date +%s -d'1 year ago'`" date
LD_PRELOAD=./libfaketime.so.1 FAKETIME_FMT=%s FAKETIME="`stat -c %Y somefile`" date
LD_PRELOAD=./libfaketime.so.1 FAKETIME_FMT=%c FAKETIME="`date`" date


4e) Advanced features and caveats
---------------------------------

Advanced time specification options:
------------------------------------

Since version 0.8, thanks to a contribution by Karl Chen, fractions can be used
in the specification of time offsets. For example,

FAKETIME="+1,5h"

is equivalent to FAKETIME="+90m". Please be aware that the fraction delimiter
depends on your locale settings, so actually you might need to use

FAKETIME="+1.5h"

You should figure out the proper delimiter, e.g. by using libfaketime on
a command like /bin/date where you immediately can verify whether it worked as
expected.

Also contributed by Karl Chen in v0.8 is the option to speed up or slow
down the wall clock time for the program which is executed using libfaketime.
For example,

FAKETIME="+1y x2"

will set the faked time one year into the future and will make the clock run
twice as fast. Similarly,

FAKETIME="+1y x0,5"

will make the clock run only half as fast. As stated above, the fraction
delimiter depends on your locale.

FAKETIME="+1y i2,0"

will make the clock step two seconds per each time(), etc. call, running
completely independently of the system clock. It helps running programs
with some determinism. In this single case all spawned processes will use
the same global clock without restarting it at the start of each process.

For testing, your should run a command like

LD_PRELOAD=./libfaketime.so.1 FAKETIME="+1,5y x10,0" \
/bin/bash -c 'while true; do echo $SECONDS ; sleep 1 ; done'

For each second that the endless loop sleeps, the executed bash shell will
think that 10 seconds have passed ($SECONDS is a bash-internal variable
measuring the time since the shell was started).

(Please note that replacing "echo $SECONDS" e.g. with a call to "/bin/date"
will not give the expected result, since /bin/date will always be started
as a new process for which also FTPL will be re-initialized. It will show
the correct offset (1.5 years in the future), but no speed-ups or
slow-downs.)

For applications that should use a different date & time each time they are
run, consider using the included timeprivacy wrapper shellscript (contributed
by adrelanos at riseup dot net).


Caveats:
--------

Whenever possible, you should use relative offsets or 'start at' dates,
and not use absolute dates.

Why? Because the absolute date/time you set is fixed, i.e., if a program
retrieves the current time, and retrieves the current time again 5
minutes later, it will still get the same result twice. This is likely to break
programs which measure the time passing by (e.g., a mail program which checks
for new mail every X minutes).

Using relative offsets or 'start at' dates solves this problem.
libfaketime then will always report the faked time based on the real
current time and the offset you've specified.

Please also note that your default specification of the fake time is cached for
10 seconds in order to enhance the library's performance. Thus, if you change the
content of $HOME/.faketimerc or /etc/faketimerc while a program is running, it
may take up to 10 seconds before the new fake time is applied. If this is a
problem in your scenario, you can change number of seconds before the file is read
again with environment variable FAKETIME_CACHE_DURATION, or disable caching at all
with FAKETIME_NO_CACHE=1. Remember that disabling the cache may negatively
influence the performance.


4f) Faking the date and time system-wide
----------------------------------------

David Burley of SourceForge, Inc. reported an interesting use case of applying
libfaketime system-wide: Currently, all virtual machines running inside
an OpenVZ host have the same system date and time. In order to use multiple
sandboxes with different system dates, the libfaketime library can be put into
/etc/ld.so.preload; it will then be applied to all commands and programs
automatically. This is of course best used with a system-wide /etc/faketimerc
file. Kudos to SourceForge, Inc. for providing the patch!

Caveat: If you run a virtual machine, its real-time clock might be reset to the
real world date & time when you reboot. Depending on your FAKETIME setting,
this may lead to side effects, such as forced file system checks on each reboot.
System-wide faked time may also lead to unexpected side effects with software
auto-update tools, if the offset between real world time and faked system time
is too large. If in doubt, set your system's date to the faked time and try out
whether everything still works as expected before applying libfaketime
system-wide.


4g) Using the "faketime" wrapper
--------------------------------

As of version 0.8, libfaketime provides a command named "faketime", which is
placed into /usr/bin by "make install". It spares the hassle of setting
the LD_PRELOAD and FAKETIME environment variables manually, but only exposes
a subset of libfaketime's functionality. On the other hand, it uses the date
interpretation function by /bin/date in order to provide higher flexibility
regarding the specification of the faked date and time. For example, you
can use

faketime 'last Friday 5 pm' /your/command/here

Of course, also absolute dates can be used, such as in

faketime '2008-12-24 08:15:42' /bin/date

Thanks to Daniel Kahn Gillmor for providing these suggestions!

Balint Reczey has rewritten the wrapper in 0.9.5 from a simple shell script
to an efficient wrapper application.


4h) "Limiting" libfaketime based on elapsed time or number of calls
--------------------------

Starting with version 0.9, libfaketime can be configured to not be continuously
active, but only during a certain time interval.

For example, you might want to start a program with the real current time, but
after 5 minutes of usage, you might want it to see a faked time, e.g., a year
in the future.

Dynamic changes to the faked time are alternatively possible by

- changing the FAKETIME environment variable at run-time; this is the preferred
  way if you use libfaketime for debugging and testing as a programmer, as it
  gives you the most direct control of libfaketime without any performance
  penalities.

- not using the FAKETIME environment variable, but specifying the fake time in a
  file (such as ~/.faketimerc). You can change the content of this file at
  run-time. This works best with caching disabled (see Makefile), but comes at a
  performance cost because this file has to be read and evaluated each time.

The feature described here works based on two pairs of environment variables,

  FAKETIME_START_AFTER_SECONDS and FAKETIME_STOP_AFTER_SECONDS, and
  FAKETIME_START_AFTER_NUMCALLS and FAKETIME_STOP_AFTER_NUMCALLS

The default value for each of these environment variables is -1, which means
"ignore this value".

If you want libfaketime to be only active during the run-time minutes 2 to 5
of your application, you would set

  FAKETIME_START_AFTER_SECONDS=60
  FAKETIME_STOP_AFTER_SECONDS=300

This means that your application will work with the real time from start (second
0) up to second 60. It will then see a faked time from run-time seconds 60 to
300 (minutes 2, 3, 4, and 5). After run-time second 600, it will again see the
real (not-faked) time.

This approach is not as flexible as changing the FAKETIME environment variable
during runtime, but may be easier to use, works on a per-program (and not a
per-user or system-wide) scope, and has only a minor performance overhead.

Using the other pair of environment variables, you can limit the activity time
of libfaketime not based on wall-clock seconds, but on the number of
time-related function calls the started program performs. This alternative is
probably only suitable for programmers who either know the code of the program
in order to determine useful start/stop values or want to perform fuzzing
tests.

Both pairs of environment variables can be combined to further restrict
libfaketime activity, although this is only useful in very few scenarios.

Limiting libfaketime activity in this way is not recommended in general. Many
programs will break when they are subject to sudden changes in time, especially
if they are started using the current (real) time and are then sent back into
the past after, e.g., 5 minutes. For example, they may appear to be frozen or
stuck because they are waiting until a certain point in time that, however, is
never reached due to the delayed libfaketime activity. Avoid using this
functionality unless you are sure you really need it and know what you are
doing.


4i) "Limiting" libfaketime per process
--------------------------------------

Faketime can be instructed to fake time related calls only for selected
commands or to fake time for each command except for a certain subset of
commands.

The environment variables are FAKETIME_ONLY_CMDS and FAKETIME_SKIP_CMDS
respectively.

Example:
    FAKETIME_ONLY_CMDS=javadoc faketime '2008-12-24 08:15:42' make
will run the "make" command but the time faking will only be applied
to javadoc processes.

Multiple commands are separated by commas.

Example:
    FAKETIME_SKIP_CMDS="javadoc,ctags" faketime '2008-12-24 08:15:42' make
will run the "make" command and apply time faking for everything "make"
does except for javadoc and ctags processes.

FAKETIME_ONLY_CMDS and FAKETIME_SKIP_CMDS are mutually exclusive, i.e.,
you cannot set them both at the same time. Faketime will terminate with
an error message if both environment variables are set.


4j) Spawning an external process
--------------------------------

From version 0.9 on, libfaketime can execute a shell command once after an
arbitrary number of seconds or number of time-related system calls of the
program started. This has two limitations one needs to be aware of:

* Spawning the external process happens during a time-related system call
  of the original program. If you want the external process to be started
  5 seconds after program start, but this program does not make any time-
  related system calls before run-time second 8, the start of your external
  process will be delayed until run-time second 8.

* The original program is blocked until the external process is finished,
  because the intercepting time-related system call will not return earlier. If
  you need to start a long-running external process, make sure it forks into the
  background.

Spawning the external process is controlled using three environment variables:
FAKETIME_SPAWN_TARGET, FAKETIME_SPAWN_SECONDS, FAKETIME_SPAWN_NUMCALLS.

Example (using bash on Linux):

(... usual libfaketime setup here, setting LD_PRELOAD and FAKETIME ...)
export FAKETIME_SPAWN_TARGET="/bin/echo 'Hello world'"
export FAKETIME_SPAWN_SECONDS=5
/opt/local/bin/myprogram

This will run the "echo" command with the given parameter during the first
time-related system function call that "myprogram" performs after running for 5
seconds.


4k) Saving timestamps to file, loading them from file
-----------------------------------------------------

Faketime can save faked timestamps to a file specified by FAKETIME_SAVE_FILE
environment variable. It can also use the file specified by FAKETIME_LOAD_FILE
to replay timestamps from it. After consuming the whole file, libfaketime
returns to using the rule set in FAKETIME variable, but the timestamp processes
will start counting from will be the last timestamp in the file.

The file stores each timestamp in a stream of saved_timestamp structs
without any metadata or padding:

/* Storage format for timestamps written to file. Big endian. */
struct saved_timestamp {
  int64_t sec;
  uint64_t nsec;
};

Faketime needs to be run using the faketime wrapper to use these files. This
functionality has been added by Balint Reczey in v0.9.5.


5. License
----------

libfaketime has been released under the GNU General Public License, GPL.
Please see the included COPYING file.


6. Contact
-----------

Bug reports, feature suggestions, success reports, and patches/pull
requests are highly appreciated:

            https://github.com/wolfcw/libfaketime

README file for libfaketime on Mac OS X
=======================================

Support for Mac OS X has meanwhile matured and many command line and
GUI applications will run stable.

Developments and tests are done on OSX 10.8+ currently, although the
current version will also work with OSX 10.7.

Version 0.9.5 and higher no longer works with OSX <= 10.6 due to
changes in the underlying system libraries. If you need libfaketime
on OSX <= 10.6, please use libfaketime version 0.9.


Installing and using libfaketime on OS X is slightly different than
on Linux. Please make sure to read the README file for general
setup and usage, and refer to this file only about OS X specifics.


1) Installing libfaketime on OS X
---------------------------------

If you use MacPorts, libfaketime can be installed on the command line
as follows:

    sudo port install libfaketime

Or, if you use Fink, install using:

    fink install libfaketime

Or, if you use Homebrew, install using:

    brew install libfaketime

Otherwise, you have to compile and install libfaketime manually; this
will require a working installation of Xcode and its command line tools
on your machine.

You can compile libfaketime by running the command

    make

in libfaketime's top-level directory.

The resulting library will be named libfaketime.1.dylib ; to check
whether it works properly, run the test suite and verify whether its
output is correct:

    cd test
    make -f Makefile.OSX


2) Using libfaketime from the command line on OS X
--------------------------------------------------

You will need to set three environment variables. In a Terminal.app
or iTerm2 session, the following commands can be used:

export DYLD_FORCE_FLAT_NAMESPACE=1
export DYLD_INSERT_LIBRARIES=/path/to/libfaketime.1.dylib
export FAKETIME="your favorite faketime-spec here"

Please refer to the general README file concerning the format
of the FAKETIME environment variable value and other environment
variables that are related to it.

The "faketime" wrapper application has been adapted to OS X;
it offers the same limited libfaketime functionality as on Linux
in a simple-to-use manner without the need to manually set
those environment variables. Run "faketime" without parameters
for help and use "man faketime" for details.


3) Integrating libfaketime with applications
--------------------------------------------

Given the limited number of system calls libfaketime intercepts,
it may not work too well with specific GUI applications on OS X.
This can result in crashes after a seemingly random time, or an
application will not or at least not always see the faked time,
and so on.

A safe way to try out whether a specific application works fine
with libfaketime is to start it from the command line. Perform
the steps outlined above and run the application by issuing the
following command:

/Applications/ApplicationName.app/Contents/MacOS/ApplicationName

(Make sure to replace "ApplicationName" twice in that command with
the name of your actual application.)

If it works fine, you can configure the application to permanently
run with libfaketime by editing its Info.plist file. Add the
LSEnvironment key unless it is already there and add a dictionary
with the three keys like this:

    <key>LSEnvironment</key>
    <dict>
        <key>DYLD_FORCE_FLAT_NAMESPACE</key>
        <string>1</string>
        <key>DYLD_INSERT_LIBRARIES</key>
        <string>/path/to/libfaketime.1.dylib</string>
        <key>FAKETIME</key>
        <string>value of FAKETIME here</string>
    </dict>

(If the application is installed in /Applications instead of in
$HOME/Applications, you eventually will need root privileges. If
the application's Info.plist is not in XML, but in binary format,
use appropriate editing or conversion tools.)

Afterwards, you will probably need to run

    /System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -v -f /Applications/ApplicationName.app

to make sure the change to Info.plist does not go unnoticed.

Please note that modifications to Info.plist will be lost when the
application is updated, so this process needs to be repeated after
such updates, including own new builds when using Xcode.

Please feel free to report non-working applications on the Github
libfaketime issues website. This may help us to identify further
time-related system calls that need to be intercepted on OS X.

    https://github.com/wolfcw/libfaketime/issues


4) Notes for developers of OS X applications
--------------------------------------------

The environment variable FAKETIME can be changed at application run-time
and always takes precedence over other user-controlled settings. It can
be re-set to 0 (zero) to work around potential incompatibilities.

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 are 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 OS X systems.

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


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 "faketime" 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 OS X 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 year. 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.