Mirage OS Logo

Contributing to MirageOS

By Mindy Preston - 2014-08-12

MirageOS welcomes contributions from anyone interested in the project. If you are planning a large contribution, be it a piece of documentation, a patch to the software, a new driver, or something else, please do send a note to the MirageOS development mailing list describing your planned contribution - you may discover that other contributors are willing to help.

More information on being in touch with other MirageOS contributors is available.

Reporting Issues

Issues (e.g. bugs in the software, unclear documentation, missing functionality) are best reported on the main MirageOS repository at GitHub, unless the issue is clearly contained in, and only relevant to, another specific repository.

When reporting an issue, please try to include any information you think may be relevant, including

  • a link to the source code you're building with MirageOS
  • relevant version info, e.g. your opam version (opam --version) and your MirageOS version (mirage --version), and your operating system and version.
  • if applicable, a terminal log representing how you trigger the issue, and what happens when the problem is occurring
  • a description of any way you may have tried to solve the issue, or gather more information about it

Submitting Changes

MirageOS uses the pull request facility of GitHub to manage patches for both code and documentation. Patches should be as self-contained as possible, with one patch corresponding to (at most) one bugfix or feature. For large changes, please coordinate with other contributors via the mailing list.

The mechanics for submitting a pull request are as follows:

  • Set up a free GitHub account.
  • Fork the repository to which you intend to commit your code. For example, a patch to the TCP/IP stack in MirageOS should fork mirage-tcpip, and a patch correcting a problem with the website's documentation should fork mirage-www.
  • Make a branch with a descriptive name for the changes you plan to make.
  • If you are making code changes, you may wish to point opam to your local repository for that code with opam pin. More details on using opam when developing are available at the opam site.
  • Make changes in your local repository. Here are some simple guidelines on commit messages.
  • When you're satisfied that your changes are ready to be submitted, push your changes to GitHub.
  • The web view for your repository should now have a button labeled submit pull request, where you can view the summary of your change and request that it be merged into the main repository.
  • Keep an eye out for notifications on your pull request! By default, GitHub will email you when other contributors have questions or comments that they'd like to discuss with you before merging your changes.