Fossil

# Fossil Push Policy

"Fossil Push Policy" or "FPP" is a proposed mechanism to help project
administrators help enforce project development policies by restricting
the kinds of changes that can be pushed up into a community server.

## Background

The default behavior of Fossil is that any developer who has push
privileges on a repository can push any content.  Project-specific
policy choices, such as "don't land unapproved changes on trunk"
or "don't reopen a closed ticket" are enforced administratively, not
by Fossil itself.  Fossil maintains a detailed audit trail so that policy
violations can be traced back to their source, and so that
violators can be duly reprimanded.  Fossil also provides mechanisms
so that unapproved changes can be excised from critical branches without
deleting history.  But by default, Fossil
does not attempt to disallow unauthorized changes from occurring in the
first place.

Nothing can prevent a developer from making non-conforming and/or
unauthorized change in a private client-side clone of a Fossil repository
since the client-side repository is under the complete control of the
developer who owns it.
Any automatic policy enforcement must happen on the common repository
when the developer attempts to push.

FPP is *not* a security mechanism.  FPP is not intended to allow
untrusted individuals to push to a common repository.  FPP does not
guarantee that no undesirable changes ever get pushed.  Rather, FPP
is designed as an administrative aid and an automatic mechanism to prevent
accidents or misunderstandings.

## Example Use Cases

Here are examples of the kinds of pushes that FPP is designed to prevent
for unauthorized users:

  *   Do not allow check-ins on trunk (or some other
      important branch).

  *   Do not allow changes to specific files within
      the project.

  *   Do not allow changes to specific wiki pages.

  *   Do not allow changes to tickets unless the ticket is in specific
      state.

  *   Do not allow new branches unless the branch name
      matches a specific GLOB, LIKE, or REGEXP pattern.

  *   Do not allow tags to be added to a check-in created by a different
      developer.

The foregoing is not an exhaustive list of the kinds of behavior that FPP
is intended to detect and prevent; it is just a representative sample of
the kinds of changes FPP is able to detect and disallow.

Rules can be written such that they apply only to specific users,
user classes — e.g. “developer” — or to everyone other than administrators.
Administrators can also be subject to FPP rules, though they have the
option to override.

## Mechanism

FPP is a set of rules contained in a single configuration setting.
The rules consist of paired Boolean expressions and error messages.
At the end of each push request received by the server, all
expressions are evaluated, and if any are true, the push
fails with its associated error message.

If a push fails, the end user will have to repair their local repository
clone before retrying the push. For example, if the trunk branch is
protected by FPP, they can amend their commit to make it appear as the
start of a new branch off trunk, at which point the push should succeed.
This is a serious inconvenience to the developer who violated the
policy, but this is intentional, intended to motivate the developer
to better follow the rules in the future.

## Client Side Warnings

FPP rules are downloaded on a "fossil clone" and on "fossil config pull fpp".
When rules exist on the client side, then certain client-side operations
(such as "fossil commit")
are also evaluated for rule violations, and appropriate warnings are issued.
However, for client-side operations, rules can always be overridden, since
the owner of the client-side clone is always administrator for their private
clone.  Early rule check-in helps prevent the client-side repository
from becoming unpushable due to typos or other accidents that would have
caused a rule violation.