CONTRIBUTING.md 5.97 KB
Newer Older
1 2 3
Contributing to Frama-C
=======================

4 5 6 7 8 9 10 11 12
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://lists.gforge.inria.fr/mailman/listinfo/frama-c-discuss);

13 14
- Reporting bugs via
  [Gitlab issues](https://git.frama-c.com/pub/frama-c/issues);
15

16 17
- [Submitting bug fixes, improvements and features](#submitting-bug-fixes-improvements-and-features)
  via Gitlab merge requests;
18

Thibaud Antignac's avatar
Thibaud Antignac committed
19
- [Developing external plug-ins](#developing-external-plug-ins)
20
  and sharing it with us through a Gitlab merge request;
21 22 23 24

- Joining the [Frama-C team](http://frama-c.com/about.html) (as an intern, a PhD
  student, a postdoctoral researcher, or a research engineer).

25
We give below some guidelines in order to ease the submission of a merge request
26 27 28
and optimize its integration with the Frama-C existing codebase.


Thibaud Antignac's avatar
Thibaud Antignac committed
29 30
Submitting bug fixes, improvements, and features
================================================
31

32 33 34 35 36
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.
37

38
The detailed steps to submit a contribution to Frama-C are:
39

40 41 42
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.
43

44 45
2. [Fork the public Frama-C repository](https://git.frama-c.com/pub/frama-c/-/forks/new)
  (choosing your Gitlab account as a destination);
46

47
3. Clone the forked Frama-C snapshot repository on your computer;
48

49 50
4. Create and switch to a dedicated branch. We suggest the following
   naming convention:
51
   - `fix/short-description` for bug fixes (correcting an incorrect
52 53
     behavior);
   - `feature/short-description` for features (adding a new behavior).
54

55
5. Locally make your contribution by adding/editing/deleting files and following
56 57
  the [coding conventions](#coding-conventions);

58
6. (Optional) Locally add non-regression test cases to the appropriate
59
  subdirectory in `./tests/`. The `hello` tutorial in the
60
  [plug-in developer manual](http://frama-c.com/download/frama-c-plugin-development-guide.pdf)
61 62 63
  provides an example of the use of the dedicated `ptests`
  tool used by Frama-C developers. The full documentation for `ptests` is also
  present later in the same manual.
64
  You can also provide the non-regression test case in the Gitlab issue
65
  discussion and we will integrate it.
66

67 68 69 70
7. Check for unexpected changes.
  Use the command `make lint`
  in your terminal from the Frama-C root directory to detect trailing spaces,
  tabulations or incorrect indentation (ocp-ident >= 1.7.0 is needed).
71

72
8. Locally run the test framework of Frama-C by typing
73
  `make tests`
74 75
  in your terminal (you should be in the Frama-C root directory);

76
9. Locally add (if needed) and commit your contribution;
77

78
10. Push your contribution to Gitlab;
79

80 81 82 83
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.
84

85
12. If needed (i.e. you didn't already do that and your contribution is
86 87
    not trivial in the sense of [this document](TCA.md)), please don't forget
    to fill and sign the [Contributor Licence Agreement](CLA.pdf) and send us
Virgile Prevosto's avatar
Virgile Prevosto committed
88
    the signed version at `cla AT frama-c DOT com`
89

90 91
For convenience, we recall the typical `git` commands to be used through these steps:
```shell
92
git clone https://git.frama-c.com/<username>/frama-c.git
93 94 95
git checkout -b <branch-name>
git diff --check
git add <file1 file 2>
96
git commit -m "<Commit message>"
97 98 99 100
git push origin <branch-name>
```
where:

101
- `<username>` is your Gitlab username;
102 103
- `<branch-name>` is your chosen branch name;
- `<file1 file2>` are the files to add to the commit;
104
- `<Commit message>` is your commit message.
105

Thibaud Antignac's avatar
minor  
Thibaud Antignac committed
106

Thibaud Antignac's avatar
Thibaud Antignac committed
107 108
Developing external plug-ins
============================
109

110 111
Frama-C is a modular platform for which it is possible to develop external
plug-ins as documented in the
112
[Plug-In development guide](http://frama-c.com/download/frama-c-plugin-development-guide.pdf).
113 114
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
115
repository as exemplified by the [Hello plug-in](https://github.com/Frama-C/frama-c-hello).
116 117 118 119

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:

120 121
1. Write your external plug-in as indicated in the
  [Plug-In development guide](http://frama-c.com/download/frama-c-plugin-development-guide.pdf);
122

123 124 125 126 127 128
2. Create an `opam` package by
  [pinning your local plug-in](http://opam.ocaml.org/doc/Packaging.html#Opam-pin) and
  [editing the `opam` file](http://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.
129

130
3. Optionally
131 132
  [publish your plug-in](http://opam.ocaml.org/doc/Packaging.html#Publishing)
  in the official OPAM packages repository.
133

134 135 136
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!
137

138 139 140
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.
Thibaud Antignac's avatar
minor  
Thibaud Antignac committed
141

Thibaud Antignac's avatar
Thibaud Antignac committed
142 143 144
Coding conventions
==================

145
- Use [ocp-indent](https://github.com/OCamlPro/ocp-indent), v1.7.0
146
  to indent OCaml source files;
Thibaud Antignac's avatar
Thibaud Antignac committed
147 148 149 150 151

- Avoid trailing whitespaces;

- Avoid using tabs;

152
- Strive to keep within 80 characters per line.