CONTRIBUTING.md 6.39 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
15
16
- Reporting bugs, via
  [Github issues](https://github.com/Frama-C/Frama-C-snapshot/issues)
  (preferred) or the
  [Mantis BTS](https://bts.frama-c.com) (older BTS);
17

Thibaud Antignac's avatar
Thibaud Antignac committed
18
- [Submitting bug fixes, improvements, and features](#submitting-bug-fixes-improvements-and-features)
19
20
  via Github pull requests;

Thibaud Antignac's avatar
Thibaud Antignac committed
21
- [Developing external plug-ins](#developing-external-plug-ins)
22
23
24
25
26
27
28
29
30
  and sharing it with us through a Github pull request;

- Joining the [Frama-C team](http://frama-c.com/about.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 pull request
and optimize its integration with the Frama-C existing codebase.


Thibaud Antignac's avatar
Thibaud Antignac committed
31
32
Submitting bug fixes, improvements, and features
================================================
33
34
35
36
37
38
39
40
41
42
43
44

Main Frama-C development happens outside Github. By default, patches and
improvements are applied upstream and only release candidates and stable
releases are pushed to Github.

Therefore, your pull requests will not be directly merged in the `master` branch
on Github. Instead, we will port them in our internal development platform and
they will be available on Github after the next Frama-C release incorporates
them.

To fit this workflow, we recommend to:

45
1. [Open an issue](https://github.com/Frama-C/Frama-C-snapshot/issues/new)
46
47
  describing your contribution.

48
2. [Fork the Frama-C snapshot repository](https://github.com/Frama-C/Frama-C-snapshot/fork)
49
50
  (choosing your Github account as a destination);

51
3. Clone the forked Frama-C snapshot repository on your computer;
52

53
54
4. Create and switch to a dedicated branch. We suggest the following
   naming convention:
55
56
57
58
59
60
  - `bugfix/username/short-description` for bug fixes (correcting an incorrect
  behaviour);
  - `improv/username/short-description` for improvements (making even better a
  functionnally correct behaviour);
  - `feature/username/short-description` for features (adding a new behaviour).

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

64
6. Optionally locally add non-regression test cases to the appropriate
65
  subdirectory in `./tests/`. The `hello` tutorial in the
66
  [plug-in developer manual](http://frama-c.com/download/frama-c-plugin-development-guide.pdf)
67
68
69
  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.
70
  You can also provide the non-regression test case in the Github issue
71
  discussion and we will integrate it.
72

73
7. Check for unexpected changes (in particular spaces and tabulations);
74

75
8. Locally run the test framework of Frama-C by typing
76
77
78
79
80
  ```shell
  make tests
  ```
  in your terminal (you should be in the Frama-C root directory);

81
82
83
84
9. Locally add (if needed) and commit your contribution. The end of the
  commit message should refer to the Github issue to which this commit is
  linked by mentioning its issue identifier preceded by `GH #` (we use the
  `GH` part to track the provenance as we use several issue trackers);
85

86
10. Push your contribution to Github;
87

88
11. [Make a Github pull request](https://github.com/Frama-C/Frama-C-snapshot/compare)
89
90
91
  (toggling the `compare across forks` view). The base fork should remain as
  `Frama-C/Frama-C-snapshot` and the base as `master` while the head fork
  should be yours and the compare should be your chosen branch name.
92

93
94
95
96
12. If needed (i.e. you didn't already do that and your contribution is
    not trivial in the sense of [this document](TCA.md), please don't forget
    to sign the [Contributor's Licence Agreement](CLA.md)

97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
For convenience, we recall the typical `git` commands to be used through these steps:
```shell
git clone https://github.com/<username>/Frama-C-snapshot.git
git checkout -b <branch-name>
git diff --check
git add <file1 file 2>
git commit -m "<Commit message> (GH #<XXX>)"
git push origin <branch-name>
```
where:

- `<username>` is your Github username;
- `<branch-name>` is your chosen branch name;
- `<file1 file2>` are the files to add to the commit;
- `<Commit message>` is your commit message;
- `<XXX>` is the Github issue identifier.

Thibaud Antignac's avatar
minor    
Thibaud Antignac committed
114

Thibaud Antignac's avatar
Thibaud Antignac committed
115
116
Developing external plug-ins
============================
117

118
119
Frama-C is a modular platform for which it is possible to develop external
plug-ins as documented in the
120
[Plug-In development guide](http://frama-c.com/download/frama-c-plugin-development-guide.pdf).
121
122
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
123
repository as exemplified by the [Hello plug-in](https://github.com/Frama-C/frama-c-hello).
124
125
126
127

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:

128
129
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);
130

131
132
133
134
135
136
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.
137

138
139
140
3. Optionnally
  [publish your plug-in](http://opam.ocaml.org/doc/Packaging.html#Publishing)
  in the official OPAM packages repository.
141

142
143
144
4. Let know the
  [Frama-C-discuss mailing list](https://lists.gforge.inria.fr/mailman/listinfo/frama-c-discuss)
  about your contribution to the Frama-C ecosystem. Well done!
145

146
The main advantage of this way to proceed is the delegation to OPAM of the task
147
148
of checking the consistency of your plug-in against
Frama-C versions (and other OCaml dependencies if any).
Thibaud Antignac's avatar
minor    
Thibaud Antignac committed
149

Thibaud Antignac's avatar
Thibaud Antignac committed
150
151
152
Coding conventions
==================

153
154
- Use [ocp-indent](https://github.com/OCamlPro/ocp-indent), v1.7.0
to indent OCaml source files;
Thibaud Antignac's avatar
Thibaud Antignac committed
155
156
157
158
159

- Avoid trailing whitespaces;

- Avoid using tabs;

160
- Strive to keep within 80 characters per line.