diff --git a/README.md b/README.md new file mode 100644 index 0000000..d3fbc8d --- /dev/null +++ b/README.md @@ -0,0 +1,42 @@ +# Rotagen + +Rotagen is a simple, configurable rota generator program. The people +available, jobs that need doing, slots available for doing jobs and +constraints/exceptions (such as someone not being available for a +particular slot or being unable to do a certain job) are specified in +a config file in an ini-like format. + +## Building + +The tool is written in C99 and has no dependencies other than the C +standard library. A Makefile is provided to build the executable on +POSIX systems; to use it to build a binary simply run `make` from the +root of the repository. + +## Running + +The tool must have a configuration file to run. The file's path can +be specified in the first command-line argument, or will default to +"rotagen.conf" in the working directory if unspecified. For example, +if your config file was at the path "~/foo.conf", you would run +`rotagen ~/foo.conf`. There is an example configuration in +`example.conf`; refer to this for the configuration file syntax. + +## Bugs / Limitations + +- The tool will hang indefinitely if it is unable to find a rota that + satisfies the constraints. +- If someone is exempted from a slot or job due to a contraint this + does not affect the probability they will be allocated to other + slots or jobs so the generated rotas are slightly unfair. +- The behaviour of ensuring someone is not allocated for two + consecutive slots is not configurable, it should be specifiable as a + constraint in the config file +- The only types of contraint that are supported are slot or job + exemptions + +## License + +Rotagen is available under the GNU Affero General Public License, +version 3, see the `LICENSE` file for details. Contributions are very +welcome and no contributor license agreement is required.