Check-in Checklist

Always run the following checklist prior to every check-in or commit to the Fossil repository:

Before every check-in:

  1. fossil user default → your username is correct.
  1. fossil diff
    1. No stray changes
    2. All changes comply with the license
    3. All inputs are scrubbed before use
    4. No injection attacks via %s formats
  1. fossil extra → no unmanaged files need to be added.
  1. The check-in will go onto the desired branch. → Check-ins to trunk normally require approval from the lead programmer (drh).
  1. auto-sync is on, or the system clock is verified
  1. If sources files have been added or removed, ensure all makefiles and configure scripts have been updated accordingly.

Before every check-in to trunk:

  1. No compiler warnings on the development machine.
  1. The fossil executable that results from a build actually works.


Before you go ahead and push content back to the servers, make sure that the username you are using by default matches your username within the project. Also remember to enable the localauth setting if you intend to make changes via a locally served web UI.

Item 1 is the most important step. Consider using gdiff instead of diff if you have a graphical differ configured. Or use the command-line option --tk. Also consider the -v command-line option to show the complete text of newly added files. The recommended command for completing checklist item 1 is:

fossil diff --tk -v

Look carefully at every changed line in item 1. Make sure that you are not about to commit unrelated changes. If there are two or more unrelated changes present, consider breaking up the commit into two or more separate commits. Always make 100% sure that all changes are compatible with the BSD license, that you have the authority to commit the code in accordance with the CLA that you have signed and have on file, and that no NDAs, copyrights, patents, or trademarks are infringed by the check-in. Also check very carefully to make sure that you are not introducing security vulnerabilities. Pay particular attention to the possibility of SQL or HTML injection attacks.

Item 2 verifies that you have not added source files but failed to do the necessary "fossil add" to manage them. If you commit without bringing the new file under source control, the check-in will be broken. That, in turn, can cause complications far in the future when we are bisecting for a bug.

For item 3, Run "fossil status" or the equivalent to make sure your changes are going into the branch you think they are. Also double-check the branch name when entering change comments. Never check into trunk unless you are expressly authorized to do so.

For Item 4, if you are on-network, make sure auto-sync is enabled. This will minimize the risk of an unintended fork. It will also give you a warning if you system clock is set incorrectly. If you are off-network, make sure that your system clock is correct or at least close to correct so that your check-in does not appear out-of-sequence on timelines. On-network commits are preferred, especially for trunk commits.

Items 6 and 7 help to ensure that check-ins on the trunk always work. Knowing that the trunk always works makes bisecting much easier. Items 6 and 7 are recommended for all check-ins, even those that are on a branch. But they are especially important for trunk check-ins. We desire that all trunk check-ins work at all times. Any experimental, unstable, or questionable changes should go on a branch and be merged into trunk after further testing.