Skip to content

Commit bbb6b93

Browse files
authored
contributions.md Add doc about how to contribute to flatbuffers (#8464)
1 parent 46cc3d6 commit bbb6b93

File tree

3 files changed

+103
-0
lines changed

3 files changed

+103
-0
lines changed

docs/README.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Documentation
2+
3+
This is the source of the FlatBuffers documentation, that is served at
4+
https://flatbuffers.dev.
5+
6+
7+
## Local Building
8+
9+
The documentation can be built and served locally during development, see [https//flatbuffers.dev/contributing/#local-development] for full details.
10+
11+
__tl;dr__
12+
13+
Install:
14+
15+
```
16+
pip install mkdocs-material
17+
```
18+
19+
Build and Serve:
20+
21+
```
22+
mkdocs serve -f docs/mkdocs.yml
23+
```

docs/mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,3 +64,4 @@ nav:
6464
- Overview: "schema.md"
6565
- Evolution: "evolution.md"
6666
- Grammar: "grammar.md"
67+
- Contributing: "contributing.md"

docs/source/contributing.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Contributing
2+
3+
We encourage community contributions to FlatBuffers through pull requests at the
4+
main
5+
[http://github.com/google/flatbuffers](http://github.com/google/flatbuffers)
6+
repository.
7+
8+
!!! note
9+
10+
The FlatBuffers project is not staffed by any full time Google employee, and
11+
is managed by a small team of 20%ers. So response time and expertise vary.
12+
13+
## Before you contribute
14+
15+
Before we can use your contributions, you __must__ sign one of the following license agreements. The agreements are self-served at the following links.
16+
17+
Our code review process will automatically check if you have signed the CLA, so
18+
don't fret. Though it may be prudent to check before spending a lot of time on
19+
contribution.
20+
21+
### Individual Contributions
22+
23+
For individuals, the [Google Individual
24+
Contributor License Agreement
25+
(CLA)](https://cla.developers.google.com/about/google-individual?csw=1) which is
26+
self served at the link. The CLA is required since you own the copyright to your
27+
changes, even after your contribution becomes part of our codebase, so we need
28+
your permission to use and distribute your code.
29+
30+
### Corporate Contributions
31+
32+
Contributions made by corporations are covered by the [Google Software Grant and
33+
Corporate Contributor License
34+
Agreement](https://cla.developers.google.com/about/google-corporate).
35+
36+
## Code Reviews
37+
38+
All submissions require a code review via Github Pull Requests.
39+
40+
1. Please adhere to the [Google Style Guide](https://google.github.io/styleguide/cppguide.html) for the language(s) you are submitting in.
41+
2. Keep PRs small and focused. Its good practice and makes it more likely your PR will be approved.
42+
3. Please add tests if possible.
43+
4. Include descriptive commit messages and context to the change/issues fixed.
44+
45+
## Documentation
46+
47+
FlatBuffers uses [MkDocs](https://www.mkdocs.org/) to generate the static
48+
documentation pages served at
49+
[https://flatbuffers.dev](https://flatbuffers.dev). Specifically, we use the
50+
[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) framework.
51+
52+
The documentation source is contained in the main repo under the
53+
[docs/](https://github.com/google/flatbuffers/tree/master/docs) directory. This
54+
[automatically](https://github.com/google/flatbuffers/blob/46cc3d6432da17cca7694777dcce12e49dd48387/.github/workflows/docs.yml#L6-L11) get built and published when the commit is made.
55+
56+
### Local Development
57+
58+
We encourage contributors to keep the documentation up-to-date as well, and it
59+
is easy to with `MkDocs` local building and serving tools.
60+
61+
First install `mkdocs-material` (see
62+
[Installation](https://squidfunk.github.io/mkdocs-material/getting-started/) for
63+
other ways)
64+
65+
```
66+
pip install mkdocs-material
67+
```
68+
69+
Then, in the `root` directory of flatbuffers, run
70+
71+
```
72+
mkdocs serve -f docs/mkdocs.yml
73+
```
74+
75+
This will continually watch the repo for changes to the documentation and serve
76+
the rendered pages locally.
77+
78+
Submit your documentation changes with your code changes and they will
79+
automatically get published when your code is submitted.

0 commit comments

Comments
 (0)