-
Notifications
You must be signed in to change notification settings - Fork 8
Expand file tree
/
Copy pathcontributing.html
More file actions
113 lines (104 loc) · 10.4 KB
/
Copy pathcontributing.html
File metadata and controls
113 lines (104 loc) · 10.4 KB
1
2
3
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
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width,initial-scale=1.0"/>
<title>Contributing to Ocsigen — Ocsigen</title>
<meta property="og:image" content="https://ocsigen.org/img/ocsigen-badge-400.png"/>
<link rel="stylesheet" href="/css/style.css"/>
<link rel="stylesheet" href="/css/ocsigen-odoc.css"/>
<link rel="stylesheet" href="/css/wodoc.css"/>
<link rel="alternate" type="text/markdown" href="/contributing.md"/>
</head>
<body class="odoc wodoc-page wodoc-home">
<!-- Shared site menu — THE single source of truth for the header, top menu and
drawer of EVERY Ocsigen doc page (vitrine + all projects). Canonical copy
lives here in ocsigen.github.io; each project's build fetches it. Injected
by `wodoc assemble --menu`. Holes filled by the tool (braces omitted here so
this comment is not itself rewritten by the hole-filler):
subproject the sub-project name shown next to the Ocsigen logo
(empty on the vitrine), via --subproject
leftnav the project's left navigation, expanded into BOTH the mobile
drawer (below) and the left column (in the page template),
via --leftnav
The current entry is highlighted by adding the `current` class to the
element carrying data-wodoc-page=<id>: --current on the vitrine (page id),
--menu-current in a project (the project id). Nothing is hardcoded here, so
this file is the ONLY place the menu is defined.
Links are the FINAL site paths (/<project>/, /<page>): the target layout
where each project is served at ocsigen.org/<project>/ — no transitional
/wodoc/ prefix. -->
<div class="page-header">
<p class="logo-ocsigen"><a href="/"><img src="/img/ocsigen-white.svg" alt="Ocsigen"/></a></p>
<div class="mainmenu">
<p class="mainmenu-home current" data-wodoc-page="githubio"><a href="/">Home</a></p>
<p class="mainmenu-doc" data-wodoc-page="tuto"><a href="/tuto/">Doc</a></p>
<p class="mainmenu-blog" data-wodoc-page="blog"><a href="/blog/">Blog</a></p>
<p data-wodoc-page="eliom"><a href="/eliom/">Eliom</a></p>
<p data-wodoc-page="js_of_ocaml"><a href="/js_of_ocaml/">Js_of_ocaml</a></p>
<p data-wodoc-page="ocsigenserver"><a href="/ocsigenserver/">Server</a></p>
<p data-wodoc-page="lwt"><a href="/lwt/">Lwt</a></p>
<p data-wodoc-page="tyxml"><a href="/tyxml/">Tyxml</a></p>
<p data-wodoc-page="ocsigen-start"><a href="/ocsigen-start/">Start</a></p>
</div>
<form id="googlesearch" action="https://google.com/search">
<input name="q" id="gsearch-box" placeholder="Search using Google"/>
<label for="gsearch-box"><img src="/img/search.svg" alt="" id="gsearch-icon"/></label>
<input type="submit" id="gsearch-submit" onclick="document.getElementById('gsearch-box').value += ' site:ocsigen.org';"/>
</form>
<aside class="how-drawer">
<input id="how-drawer-toggle" type="checkbox"/>
<label for="how-drawer-toggle" id="how-drawer-label"><span class="how-drawer-icon"></span></label>
<nav class="how-drawer-content">
<ul class="drawermainmenu">
<li class="drawermainmenu-home current" data-wodoc-page="githubio"><a href="/">Home</a></li>
<li class="drawermainmenu-doc" data-wodoc-page="tuto"><a href="/tuto/">Doc</a></li>
<li class="drawermainmenu-project" data-wodoc-page="eliom"><a href="/eliom/">Eliom</a></li>
<li class="drawermainmenu-project" data-wodoc-page="js_of_ocaml"><a href="/js_of_ocaml/">Js_of_ocaml</a></li>
<li class="drawermainmenu-project" data-wodoc-page="ocsigenserver"><a href="/ocsigenserver/">Server</a></li>
<li class="drawermainmenu-project" data-wodoc-page="lwt"><a href="/lwt/">Lwt</a></li>
<li class="drawermainmenu-project" data-wodoc-page="tyxml"><a href="/tyxml/">Tyxml</a></li>
<li class="drawermainmenu-project" data-wodoc-page="ocsigen-toolkit"><a href="/ocsigen-toolkit/">Toolkit</a></li>
<li class="drawermainmenu-project" data-wodoc-page="ocsigen-start"><a href="/ocsigen-start/">Start</a></li>
<li class="drawermainmenu-project" data-wodoc-page="ocsipersist"><a href="/ocsipersist/">Ocsipersist</a></li>
<li class="drawermainmenu-project" data-wodoc-page="reactiveData"><a href="/reactiveData/">ReactiveData</a></li>
<li class="drawermainmenu-project" data-wodoc-page="ocsigen-i18n"><a href="/ocsigen-i18n/">i18n</a></li>
<li class="drawermainmenu-project" data-wodoc-page="wodoc"><a href="/wodoc/">Wodoc</a></li>
<li class="drawermainmenu-page" data-wodoc-page="projects"><a href="/projects">Other projects</a></li>
<li class="drawermainmenu-page" data-wodoc-page="papers"><a href="/papers">Research papers</a></li>
<li class="drawermainmenu-page" data-wodoc-page="credits"><a href="/credits">Who does Ocsigen?</a></li>
<li class="drawermainmenu-page" data-wodoc-page="contributing"><a href="/contributing">Contributing</a></li>
<li class="drawermainmenu-page" data-wodoc-page="blog"><a href="/blog/">Blog</a></li>
<li class="drawermainmenu-page" data-wodoc-page="install"><a href="/install">Installation</a></li>
<li class="drawermainmenu-page"><a href="https://github.com/ocsigen">Source code</a></li>
</ul>
<!-- On mobile the left column is hidden; its menu lives here in the burger
(.how-doctree, shown only on narrow screens), as the old site did.
Empty on the vitrine; the leftnav hole is filled (with the same
fragment as the left column) only on project pages. -->
<nav class="how-doctree"></nav>
</nav>
</aside>
</div>
<div class="project-page"><div class="rightcol"><h1 id="contributing-to-ocsigen">Contributing to Ocsigen</h1>
<h2 id="for-individual-contributors">For individual contributors</h2><p>To contribute to an Ocsigen project, first see the guidelines it provides. It will give you the directives on how to make your contribution. Once ready, create a <em>Pull Request</em> on the repository and wait for feedback!</p><p><b>Every contribution has to be documented!</b> The documentation now lives <b>in the project's own repository</b>, alongside the code: hand-written manual pages as <code>doc/*.mld</code> files and API documentation as comments in the <code>.mli</code> files, all in <a href="https://ocaml.github.io/odoc/">odoc</a> syntax. A single pull request on the project's main branch therefore carries both your code <em>and</em> its documentation — there is no separate documentation branch anymore (the old <code>wikidoc</code> branch and the wikicréole format are gone).</p><p>The CI checks that the documentation builds without errors on every push to your branch, and, once merged, rebuilds and publishes it automatically to the project's <code>gh-pages</code> branch, served at <a href="https://ocsigen.org">https://ocsigen.org</a>. Do not hesitate to ask for help if you experience any trouble.</p><h2 id="create-a-release-(for-package-maintainers)">Create a release (for package maintainers)</h2><ol><li>Make sure the documentation sources (<code>doc/*.mld</code> and the <code>.mli</code> comments) are <b>up to date</b> with the code on <code>master</code>; the CI rebuilds the <code>dev</code> docs on every push to <code>master</code>.</li><li>Freeze the current <code>dev</code> docs as the new version on the project's <code>gh-pages</code> branch: <code>wodoc release --site . --version X.Y.Z</code> (copies <code>dev/</code> to <code>X.Y.Z/</code> and repoints the <code>latest</code> symlink), then commit and push.</li><li>Update file CHANGES</li><li>On <code>master</code>, update opam configuration file.</li><li><code>git tag <version></code> then <code>git push --tags</code></li><li>Create a release on GitHub.</li><li><code>opam publish</code> and wait for the package to be accepted.</li></ol><ol><li>Add a file in directory <code>_posts</code> of repository <code>ocsigen.github.io</code> on Github to create a blog post that will be published on OCaml Planet and Twitter's OCaml page</li></ol><h2 id="local-documentation-generation">Local documentation generation</h2><p>Every project's documentation is built by <a href="/wodoc/">wodoc</a> (an odoc driver) from its <code>.mld</code> manual pages and <code>.mli</code> API comments, configured by a single <code>doc/wodoc</code> file in the project. To build it locally, from the project root:</p><pre class="language-ocaml"><code>wodoc build --config doc/wodoc --out _doc-site/dev --label dev \
--menu https://ocsigen.org/doc/menu.html --local</code></pre><p><code>--local</code> also fetches the shared <code>/css/</code> and <code>/img/</code> assets so the result is viewable offline (<code>cd _doc-site && python3 -m http.server</code>, then open <code>localhost:8000/dev/</code>). See the project's <code>doc/README.md</code> for the exact command and the opam switch it needs.</p><h2 id="main-site">Main site</h2><p>The vitrine (this site's home, projects, install, credits, papers, contributing) lives in repository <code>ocsigen.github.io</code>, branch <code>master</code>, directory <code>doc/vitrine/</code> (<code>.mld</code> sources). The two archived projects served directly from this repository, <code>ocsimore</code> and <code>html_of_wiki</code>, live in <code>doc/ocsimore/</code> and <code>doc/html_of_wiki/</code>. A GitHub Action (<code>.github/workflows/doc.yml</code>) rebuilds them with wodoc on every push to <code>master</code> — nothing to run by hand. Every other (active) project builds and publishes its own documentation to its own <code>gh-pages</code> branch, served at <code>ocsigen.org/<project>/</code>.</p></div></div>
<div class="main-page-section main-page-section-about">
<div class="main-page-section-content">
<ul>
<li><a href="credits.html">Who does Ocsigen?</a></li>
<li><a href="papers.html">Research papers</a></li>
<li><a href="projects.html">All the projects</a></li>
<li><a href="contributing.html">Contributing</a></li>
<li><a href="/blog/">Blog</a></li>
<li><a href="install.html">Installation</a></li>
<li><a href="https://github.com/ocsigen">Source code</a></li>
</ul>
</div>
</div>
<!-- shared Ocsigen highlighter: odoc's bundled highlight.js + wodoc-highlight.js
(Ocsigen OCaml extensions + highlightAll), same engine as the blog and docs. -->
<script src="/doc/highlight.pack.js"></script>
<script src="/doc/wodoc-highlight.js"></script>
</body>
</html>