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

4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
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);

- Reporting bugs (via
  [Github issues](https://github.com/Frama-C/Frama-C-snapshot/issues)) or the
  [Mantis BTS](https://bts.frama-c.com);

- [Submitting bug fixes, improvements, and features](#submitted-bug-fixes-improvements-and-features)
  via Github pull requests;

- [Developing your own plug-in](#external-plug-ins)
  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.


Submitted bug fixes, improvements, and features
===============================================

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:

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

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

50
3. Clone the forked Frama-C snapshot repository on your computer by typing
51
52
53
54
55
  ```shell
  git clone https://github.com/username/Frama-C-snapshot.git
  ```
  in your terminal (change `username` by your Github username);

56
4. Create and switch in a dedicated branch by typing 
57
58
59
60
61
62
63
64
65
66
67
  ```shell
  git checkout -b branch-name
  ```
  in your terminal (change `branch-name` by your chosen branch name). The chosen
  branch name should follow the following convention:
  - `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).

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

71
6. Optionally locally add non-regression test cases to the appropriate
72
73
74
75
76
77
78
  subdirectory in `./tests/`. The
  [plug-in developer manual](http://frama-c.com/download/frama-c-plugin-development-guide.pdf)
  exemplifies the use of the dedicated `ptests` tool used by Frama-C developers
  in its `hello` tutorial and provides a documentation of it in a full section.
  You can also provide the non-regression test case in the Github issue
  discussion and we will integrate it).

79
7. Check for unexpected changes (in particular spaces and tabulations) by typing
80
81
82
83
84
  ```shell
  git diff --check
  ```
  in your terminal.

85
8. Locally run the test framework of Frama-C by typing
86
87
88
89
90
  ```shell
  make tests
  ```
  in your terminal (you should be in the Frama-C root directory);

91
9. Locally add (if needed) and commit your contribution by typing
92
93
  ```shell
  git add -A
Thibaud Antignac's avatar
minor    
Thibaud Antignac committed
94
  git commit -m "Commit message (GH #XXX)"
95
96
97
98
99
100
101
  ```
  in your terminal (this adds all the new files to the commit, you can pick the
  relevant files as described in the
  [`Git` documentation](https://git-scm.com/docs/git-add)). The end of the
  commit message should refer the Github issue to which this commit is linked
  and thus #XXX replaced by the corresponding number;

102
10. Push your contribution to Github by typing
103
104
105
106
107
  ```shell
  git push origin branch-name
  ```
  in your terminal (change `branch-name` by the right branch name);

108
11. [Make a Github pull request](https://github.com/Frama-C/Frama-C-snapshot/compare)
109
110
111
  (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.
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

Coding conventions
==================

- Use [ocp-indent](https://github.com/OCamlPro/ocp-indent) to indent files;

- Avoid trailing whitespaces;

- Avoid using tabs;

- Strive to keep within 80 characters per line.

External plug-ins
=================

127
128
129
130
131
Frama-C is a modular platform for which it is possible to develop external
plug-ins as documented in the
[Plug-in Development Guide](http://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
132
133
134
135
136
repository.

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:

137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
1. [Fork the Frama-C snapshot repository](https://github.com/Frama-C/Frama-C-snapshot/fork)
  (choosing your Github account as a destination);

2. Clone the forked Frama-C snapshot repository on your computer by typing
  ```shell
  git clone https://github.com/username/Frama-C-snapshot.git
  ```
  in your terminal (change `username` by your Github username);

3. Locally make your contribution by adding/editing/deleting files in the
  `./src/plugins/` directory, along with appropriate
   `configure.ac` and `Makefile.in` files, and following
  the [coding conventions](#coding-conventions);

4. Optionnally locally add non-regression test cases to the appropriate
  subdirectory in `./tests/`. The
  [plug-in developer manual](http://frama-c.com/download/frama-c-plugin-development-guide.pdf)
  exemplifies the use of the dedicated `ptests` tool used by Frama-C developers
  in its `hello` tutorial and provides a documentation of it in a full section.
  You can also provide the non-regression test case in the Github issue
  discussion and we will integrate it).

5. Locally run the test framework of Frama-C by typing
  ```shell
  make tests
  ```
  in your terminal (you should be in the Frama-C root directory);

6. Locally add (if needed) and commit your contribution by typing
  ```shell
  git add -A
  git commit -m "Commit message"
  ```
  in your terminal (this adds all the new files to the commit, you can pick the
  relevant files as described in the
  [`Git` documentation](https://git-scm.com/docs/git-add));

7. Push your contribution to Github by typing
  ```shell
  git push -u origin branch-name
  ```
  in your terminal (change `branch-name` by the right branch name).
179
180
181
182

This will ensure that (1) the version of Frama-C that is available with your
plug-in is guaranteed to compile and work, independently of API changes;
(2) updating your plug-in will only require synchronizing with the
183
Frama-C snapshot repository.