Newer
Older
Contributing to Frama-C
=======================
We always welcome technical as well as non-technical contributions from the
community.
There are several ways to participate in the Frama-C project:
- Asking questions and discussing at
[StackOverflow](https://stackoverflow.com/tags/frama-c) and through
the
[Frama-C-discuss mailing list](https://groupes.renater.fr/sympa/info/frama-c-discuss);
- Reporting bugs via
[Gitlab issues](https://git.frama-c.com/pub/frama-c/issues);
- [Submitting bug fixes, improvements and features](#submitting-bug-fixes-improvements-and-features)
via Gitlab merge requests;
- [Developing external plug-ins](#developing-external-plug-ins)
and sharing it with us through a Gitlab merge request;
- [Joining the Frama-C team](https://frama-c.com/html/jobs.html) (as an intern, a PhD
student, a postdoctoral researcher, or a research engineer).
We give below some guidelines in order to ease the submission of a merge request
and optimize its integration with the Frama-C existing codebase.
Submitting bug fixes, improvements, and features
================================================
External contributions can be proposed via the
public Frama-C gitlab [repository](https://git.frama-c.com/pub/frama-c),
by following the recommended workflow in git development:
fork the frama-c repository, develop in a dedicated branch
and submit a merge request.
Note: these steps assume that you have an account in Frama-C's Gitlab instance.
This can be done by signing in via Github (which, in turn, requires a Github
account; if you do not have a Github account, please contact us by e-mail).
The detailed steps to submit a contribution to Frama-C are:
1. If you plan to make a significant contribution to Frama-C, please
[open an issue](https://git.frama-c.com/pub/frama-c/issues/new)
describing your ideas, to discuss it with the Frama-C development team.
2. [Fork the public Frama-C repository](https://git.frama-c.com/pub/frama-c/-/forks/new)
(choosing your Gitlab account as a destination);
3. Clone the forked Frama-C repository on your computer;
4. Create and switch to a dedicated branch. We suggest the following
naming convention:
- `fix/short-description` for bug fixes (correcting an incorrect
behavior);
- `feature/short-description` for features (adding a new behavior).
5. Locally make your contribution by adding/editing/deleting files and following
the [coding conventions](#coding-conventions);
6. (Optional) Locally add non-regression test cases to the appropriate
subdirectory in `./tests/` or `./src/plugins/<plugin>/tests/`.
Consult the [plug-in developer manual](https://frama-c.com/download/frama-c-plugin-development-guide.pdf)
for details on how to run tests inside Frama-C.
You can also provide the non-regression test case in the Gitlab issue
discussion and we will integrate it.
7. Check for unexpected changes.
in your terminal from the Frama-C root directory to detect trailing spaces,
tabulations or incorrect indentation (ocp-indent = 1.8.1, camomile,
clang-format and black (Python linter) are needed), and `make lint` to fix
problems if any.
Use the command `make check-headers` in your terminal from the Frama-C root
directory to detect incorrect file licenses (the `headache` opam package is
needed), and `make headers` to fix them.
8. Locally run the test framework of Frama-C by typing
`make default-tests`
in your terminal (you should be in the Frama-C root directory).
9. Locally add (if needed) and commit your contribution.
10. Push your contribution to Gitlab.
11. [Make a Gitlab merge request](https://git.frama-c.com/pub/frama-c/merge_requests).
The target should remain as repository `pub/frama-c` and branch `master`
while the source should be your personal project and your chosen branch
name.
12. If needed (i.e. it is your first non-trivial contribution in the sense of
[this document](TCA.md)), please do not forget to fill and sign the
[Contributor Licence Agreement](CLA.pdf) and send us the signed version at
`cla AT frama-c DOT com`.
For convenience, we recall the typical `git` commands to be used through these steps:
```shell
git clone https://git.frama-c.com/<username>/frama-c.git
git checkout -b <branch-name>
git diff --check
git add <file1 file2 ...>
git commit -m "<Commit message>"
git push origin <branch-name>
```
where:
- `<username>` is your Gitlab username;
- `<branch-name>` is your chosen branch name;
- `<file1 file2 ...>` are the files to add to the commit;
- `<Commit message>` is your commit message.
Developing external plug-ins
============================
Frama-C is a modular platform for which it is possible to develop external
plug-ins as documented in the
[Plug-In development guide](https://frama-c.com/download/frama-c-plugin-development-guide.pdf).
Such plug-ins normally do not require changes to the Frama-C source code and can
be developed completely independently, for instance in a separate Git
However, to make it easier for your users to compile and use your plug-in, even
as newer releases are made available, we recommend the following workflow:
1. Write your external plug-in as indicated in the
[Plug-In development guide](https://frama-c.com/download/frama-c-plugin-development-guide.pdf);
2. Create an `opam` package by
[pinning your local plug-in](https://opam.ocaml.org/doc/Packaging.html#Opam-pin) and
[editing the `opam` file](https://opam.ocaml.org/doc/Packaging.html#The-quot-opam-quot-file).
You can have a look at the
[`opam` file of the Hello plug-in](https://github.com/Frama-C/frama-c-hello/blob/master/opam)
if necessary.
[publish your plug-in](https://opam.ocaml.org/doc/Packaging.html#Publishing)
in the official OPAM packages repository.
4. Announce your contribution to the Frama-C ecosystem on the
[Frama-C-discuss mailing list](https://lists.gforge.inria.fr/mailman/listinfo/frama-c-discuss).
Well done!
The main advantage of this procedure is that opam will perform several
consistency checks of your plug-in,
with respect to several Frama-C versions and OCaml dependencies.
- Use [ocp-indent](https://github.com/OCamlPro/ocp-indent), v1.8.1
to indent OCaml source files (available from `opam`);
- Use [black](https://pypi.org/project/black/) to indent Python source files;
- Use [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to indent C
files (mostly for E-ACSL, and possibly tests);
- Avoid trailing whitespaces;
- Avoid using tabs;
- Strive to keep within 80 characters per line.