Move contributing guide to a man page.

2022-09-23 08:54:47 -04:00 · 2022-09-23 08:54:47 -04:00 · 5178fd2d21
commit 5178fd2d21
parent 55967c2d75
2 changed files with 247 additions and 248 deletions
--- a/docs/contributing.7
+++ b/docs/contributing.7
@ -7,4 +7,246 @@
 .Sh DESCRIPTION
 Telodendria is an open source project. As such, it welcomes
 contributions. There are many ways you can contribute, and any
-way you can is greatly appreciated.
+way you can is greatly appreciated. This page contains some of
 the ways you can help out.
 .Sh REPORTING ISSUES
 Please reach out to the Matrix rooms mentioned at the top of
 .Xr telodendria 7 .
 All issue tracking takes place in those rooms. Start by reaching
 out to the general room, and if you think there's a legitimate
 problem with Telodendria itself, then stick the issue in the
 issues room, where it can be discussed further. Issues usually
 remain in the Matrix rooms, but severe enough issues may be put
 in a
 .Pa TODO
 file in the
 .Xr cvs 1
 repository so that they don't get lost.
 .Sh DEVELOPING
 The primary language used to write Telodendria code is ANSI C.
 Other languages you'll find in the Telodendria repository include
 shell scripts, 
 .Xr mdoc 7 ,
 and a little bit of HTML and CSS. If you have any experience with
 any of these languages, your contributions are valuable! Please follow
 the guidelines on this page to ensure the contribution workflow goes
 as smoothly as possible.
 .Ss Getting the Code
 If you'd like to hack on Telodendria, you'll need the following tools
 in addition to a C compiler and POSIX shell:
 .Bl -tag
 .It Xr cvs 1
 For checking out and updating your local copy of the source code.
 .It Xr indent 1
 For formatting your code before generating patches.
 .It Xr patch 1
 For applying patches to your local copy of the source code.
 .El
 .sp
 All of these tools are built into OpenBSD. While you don't have to
 use OpenBSD to develop Telodendria, it may make the process a bit
 easier. In fact, these tools where chosen precisely because they
 were built into my operating system of choice.
 .sp
 You can download an official release tarball from the website if
 you would really like, but the preferred way to get the source
 code for development is to check it out from CVS. This makes generating
 patches a lot easier.
 .Bd -literal -offset indent
 $ cvs -d anoncvs@bancino.net:/cvs checkout -P Telodendria
 $ cd Telodendria
 .Ed
 .sp
 If you already checked out the code previously, make sure you update
 your local copy before you start developing:
 .Bd -literal -offset indent
 $ cvs -q update -dP
 .Ed
 .sp
 You should now have the latest source code. Follow the
 .Sx CODE STYLE
 as you make your changes. If the
 .Xr cvs 1
 command fails with a "Connection refused" error message, try setting
 the
 .Ev CVS_RSH
 environment variable to "ssh", like this:
 .Bd -literal -offset indent
 $ export CVS_RSH=ssh
 .Ed
 .sp
 Then run the checkout command again. Some versions of CVS on some
 systems don't use SSH to checkout by default, so if yours doesn't,
 you might want to put the above line into your shell init script.
 .Ss Submitting Patches
 Telodendria aims at remaining as minimal as possible. This doesn't just
 mean minimal code, it also means a minimal development process, which is
 why Telodendria doesn't use GitHub, GitLab, or even SourceHut. Instead,
 the contribution workflow operates on submitting patch files to a public
 Matrix room, sort of like the OpenBSD project operates on patch files
 sent to a public mailing list.
 .sp
 If you're not used to manually creating and submitting patches instead of
 just opening a "pull request," you should be pleased to hear that submitting
 patches is fairly easy to do if you've got the CVS sources checked out. In
 fact, I find it easier than having to make a GitHub account, forking a
 project's repository, and then making a pull request for it. Once you have
 made your changes in your local copy of the code, and you've configured your
 environment properly as noted in the manual for
 .Xr td 8 ,
 just run the patch recipe:
 .Bd -literal -offset indent
 $ td patch
 .Ed
 .sp
 This will automatically generate a patch file for all your changes, and then
 open it in your preferred editor. You can also generate a patch file for only
 certain files and directories. To do that, set
 .Ev PATCHSET ,
 like this:
 .Bd -literal -offset indent
 # Only write a patch for README.txt and the files in docs/
 $ PATCHSET="README.txt docs/" td patch
 .Ed
 .sp
 As you'll notice, the top of the patch file should have some email-style
 headers that look like this:
 .Bd -literal -offset indent
 From: Jordan Bancino <@jordan:bancino.net>
 Date: Fri Jul 29 03:21:21 PM EDT 2022
 Subject: Document Patch Procedure
 .Ed
 .sp
 As much information should be filled out for you, such as the date. An
 attempt to fill out the From header was also made by
 .Xr td 8 ,
 but the information there can be modifed as necessary. Consult the manual
 for
 .Xr td 8
 for more details. The Subject should very briefly describe what the patch
 is about.
 .sp
 You'll also notice these lines in the patch:
 .Bd -literal -offset indent
 [ ] I have read the Telodendria Project development certificate of
    origin, and certify that I have permission to submit this patch
    under the conditions specified in it.
 .Ed
 .sp
 This is a checkbox that tells me whether or not you actually have the
 rights to submit your patch, and that once you submit your patch, your
 code is bound by the Telodendria project license, which you can and
 should view in
 .Xr telodendria 7 .
 The full text of the developer certificate of origin is as follows:
 .Bl -enum
 .It
 The contribution was created in whole or in part by me, and I have the right
 to submit it under the open source licenses of the Telodendria project; or
 .It
 The contribution is based upon a previous work that, to the best of my knowledge,
 is covered under an appropriate open source license and I have the right under
 that license to submit that work with modifications, whether created in whole
 or in part by me, under the Telodendria project license; or
 .It
 The contribution whas provided directly to me by some other person who certified
 (1), (2), or (3), and I have not modifed it.
 .It
 I understand and agree that this project and the contribution are made public
 and that a record of the contribution\(emincluding all personal information
 I submit with it\(emis maintained indefinitely and may be redistributed
 consistent with this project or the open source licenses involved.
 .El
 .sp
 If you agree to the above, fill in the square brackets with an 'x', and then after
 the headers, but before the checkbox, write a more thorough description of the
 patch and why it was created. Then, send the resulting patch file to the public
 Matrix room, as noted in
 .Xr telodendria 7 ,
 so it can be discussed and reviewed by the community.
 .sp
 Try to keep your patches on topic\(emmake one patch file per feature or bug fix
 being implemented. It is okay if your patches depend on previous patches, just
 indicate that in the patch description. Note that it may take a while for
 patches to be committed, and some patches may not be comitted at all. In either
 case, all sent patches are queued from the Matrix room into the public patch
 directory, so they can be referenced easier in the future. If you want to
 reference a submitted patch in a Matrix message, email, or other digital medium,
 it might be a good idea to link to it in the public patch directory.
 .sp
 The public patch directory works as follows: when you send your patch to the
 Matrix room, it is downloaded by Telodendria Bot and placed in the
 .Pa ingress/
 directory, named as the message ID. Then, it is assigned a patch ID and
 copied to the
 .Pa p/
 directory as just "%d.patch", where "%d" is obviously the patch ID. This is
 a permanent link that will always reference your patch. Then, your patch will
 be symlinked into the 
 .Pa queue/
 directory. I have a script that automatically ingresses patches and queues them
 for me, and I use this to review patches. If your patch is accepted, the queue
 symlink will be moved to
 .Pa accepted/
 and the submitted patch will be committed to the official CVS repository.
 If your patch is rejected for some reason, its symlink will be moved to the
 .Pa rejected/
 directory. Regardless of the state of your patch, it will always remain
 permalinked in the
 .Pa p/
 directory, and when it is accepted or rejected, Telodendria Bot will send a
 message to the Matrix room.
 .sp
 You're always welcome to inquire about rejected patches, and request that they
 be reviewed again, or you can use them as a starting point for future patches.
 .sp
 The public patch directory is located at
 .Lk https://telodendria.io/patches/
 .Sh CODE STYLE
 In general, these are the conventions used by the code base. This guide
 may be slightly outdated or subject to change, but it should be a good
 start. The source code itself is always the absolute source of truth, so
 as long as you make your code look like the code surrounding it, you should
 be fine.
 .Bl -bullet
 .It
 All function, enumeration, structure, and header names are CamelCase. This
 is preferred to snake_case because it is more compact.
 .It
 All variable names are lowerCamelCase. This is preferred to snake_case
 because it is more compact.
 .It
 enumerations and structures are always typedef-ed to their same name. The
 typedef should occur in the public API header, and the actual declaration
 should live in the implementation file.
 .It
 A feature of the code base lives in a single C source file that has a
 matching header. The header file should only export public symbols;
 everything else in the C source should be static.
 .It
 Except where absolutely necessary, global variables are forbidden to
 prevent problems with threads and whatnot. Every variable a function
 needs should be passed to it either through a structure, or as a
 separate argument.
 .It
 Anywhere curly braces are optional, there still must be curly braces. This
 makes it easier to add on to the code later, and just makes things a bit
 less ambiguous.
 .El
 .sp
 As far as actually formatting the code goes, such as where to put brackets,
 and whether or not to use tabs or spaces, use
 .Xr indent 1
 to take care of all of that. The root of the CVS repository has a
 .Pa .indent.pro
 that should automatically be loaded by
 .Xr indent 1
 to set the correct rules. If you don't have a working
 .Xr indent 1 ,
 then just indicate in your patch that I should run my
 .Xr indent 1
 on the code after applying it. Although in reality, I'll likely
 run my own
 .Xr indent 1
 on the code anyway, just to make sure the spacing is consistent, if nothing
 else.
--- a/site/index.html
+++ b/site/index.html
@ -176,9 +176,10 @@ configure it, as well as contribute to the project. The <code>man</code>
 pages are also available online for convenience:
 </p>
 <ul>
-<li><a href="telodendria.7.html">telodendria(7)</a> - Introduction</li>
+<li><a href="telodendria.7.html">telodendria(7)</a> - Introduction and project information, including licensing information</li>
-<li><a href="telodendria.8.html">telodendria(8)</a> - Command line</li>
+<li><a href="telodendria.8.html">telodendria(8)</a> - Command line usage</li>
 <li><a href="telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration file</li>
 <li><a href="contributing.7.html">contributing(7)</a> - Contributing guide</li>
 <li><a href="td.8.html">td(8)</a> - Build script and patch instructions</li>
 </ul>
 <h2 id="project-status">Project Status</h2>
@ -192,7 +193,7 @@ getting off the ground and building a foundation.
 But just because there's nothing here yet doesn't mean you should go away!
 I could always use help, so you are more than welcome to help
 out if you want things to go quicker. Please see the
-<a href="#contributing">Contributing</a> section for details on how you
+<a href="contributing.7.html">contributing(7)</a> page for details on how you
 can get involved.
 </p>
 <p>
@ -369,250 +370,6 @@ you do though, make sure you're running the latest version of
 <b>Telodendria</b> and you've thoroughly read through all the
 relevant documentation.
 </p>
 <h2 id="contributing">Contributing</h2>
 <p>
 <b>Telodendria</b> is an open source project. As such, it welcomes
 contributions. There are many ways you can contribute, and any way you
 can is greatly appreciated.
 </p>
 <h3 id="reporting-issues">Reporting Issues</h3>
 <p>
 If&mdash;after you've reached out to
 <code>#telodendria-general:bancino.net</code>&mdash;it has been
 determined that there is a problem with <b>Telodendria</b>, it should
 be reported to <code>#telodendria-issues:bancino.net</code>. There it
 can be discussed further. The issues room serves as the official
 issue tracker of <b>Telodendria</b>; although severe issues may be copied
 into a <code>TODO</code> file in the CVS repository just so they
 don't get lost.
 </p>
 <h3 id="developing">Developing</h3>
 <p>
 The primary language used to write <b>Telodendria</b> code is ANSI C.
 Other languages you'll find in the
 <b>Telodendria</b> repository are shell scripts and HTML. If you have
 any experience at all with any of these languages, your contributions
 are valuable. Please follow the guidelines in this section to ensure
 the contribution workflow goes as smoothly as possible.
 </p>
 <h4 id="getting-the-code">Getting The Code</h4>
 <p>
 If you'd like to hack on <b>Telodendria</b>, you'll need the following
 tools in addition to the tools required to
 <a href="#building-the-source">build the source</a>:
 </p>
 <ul>
 <li><code>cvs</code> for checking out and updating a local copy
 of the source code.</li>
 <li><code>indent</code> for formatting your code before generating
 patches</li>
 <li><code>patch</code> for applying patches to your local copy of the
 source code.</li>
 </ul>
 <p>
 Note that all of these tools are built into OpenBSD. While you of course
 don't have to use OpenBSD to develop <b>Telodendria</b>, it may make
 the process a little easier. In fact, these tools were chosen
 precisely <i>because</i> they were built into OpenBSD, the operating
 system I use.
 </p>
 <p>
 You can download an official release tarball if you would really like,
 but the preferred way is to check out the source code from CVS. This
 makes generating patches a lot easier. 
 </p>
 <div class="code">
 $ cvs -d anoncvs@bancino.net:/cvs checkout -P Telodendria
 $ cd Telodendria
 </div>
 <p>
 If you already checkout out the code previously, make sure you update your
 local copy before you start developing:
 </p>
 <div class="code">
 $ cvs -q update -dP
 </div>
 <p>
 You should now have the latest <b>Telodendria</b> source code. Follow
 the <a href="#code-style">Code Style</a> as you make your changes. If
 the <code>cvs</code> command fails with a <code>Connection refused</code>
 error message, then try setting the <code>CVS_RSH</code> environment
 variable to <code>ssh</code>, like this:
 </p>
 <div class="code">
 $ export CVS_RSH=ssh
 </div>
 <p>
 Then run the checkout again. Some versions of CVS don't use SSH to checkout
 by default, so if yours doesn't, you might want to put that line in your
 <code>.bashrc</code> or other shell init script.
 </p>
 <h4 id="code-style">Code Style</h4>
 <p>
 In general, these are the conventions used by the code base. This
 guide may be slightly outdated or subject to change, however. The
 source code itself is the absolute source of truth, so as long as
 you make your code look like the code surrounding it, you should
 be fine.
 </p>
 <ul>
 <li>
 All function, enumeration, structure, and header names are
 <code>CamelCase</code>. This is preferred to <code>snake_case</code>
 because it is more compact.
 </li>
 <li>
 All variable names are <code>lowerCamelCase</code>. This is preferred
 to <code>snake_case</code> because it is more compact.
 </li>
 <li>
 <code>enum</code>s and <code>struct</code>s are always
 <code>typedef</code>-ed to their same name. The <code>typedef</code>
 occurs in the public API header, and the actual declaration occurs in
 the implementation file.
 </li>
 <li>
 A feature of the code base lives in a single <code>.c</code> file that
 has a matching header file. The header file should only export public
 symbols, everything else in the <code>.c</code> file should be
 <code>static</code>.
 </li>
 <li>
 Anywhere curly braces are optional, there must still be curly braces.
 This makes it easy to add on to the code later, and just makes things
 less ambiguous.
 </li>
 </ul>
 <p>
 As far as actually formatting the code goes, such as where to put
 brackets and whether you use tabs or spaces, use <code>indent(1)</code>
 to take care of all of that. The root of the repository has a
 <code>.indent.pro</code> file that should automatically be loaded by
 <code>indent(1)</code> to set the correct rules. If you don't have
 access to a working <code>indent(1)</code>, just indicate in your patch
 that I should run <code>indent(1)</code> on the code after applying it.
 I'll likely run my <code>indent(1)</code> on the code anyway though,
 just to make sure the spacing is consistent, if nothing else.
 </p>
 <h4 id="submitting-patches">Submitting Patches</h4>
 <p>
 <b>Telodendria</b> aims at remaining as minimal as possible. This doesn't
 just mean minimal code, it also means a minimal development process, which
 is why <b>Telodendria</b> doesn't use GitHub, GitLab, or even SourceHut.
 Instead, the contribution workflow operates on submitting patch files to
 a public Matrix room, sort of like the OpenBSD project operates on patch
 files sent to a public mailing list.
 </p>
 <p>
 If you're not used to manually creating and submitting patches instead of
 opening a "pull request," you should be pleased to hear that submitting
 patches is fairly easy to do if you've got the CVS sources checked out.
 In fact, I find it easier than having to make a GitHub account, forking
 a project repository, and then making a pull request for it. Once you
 have made your changes in your local copy of the code, and you've
 configured your environment using the instructions in
 <a href="#the-build-script">The Build Script</a>, just run the
 <code>patch</code> recipe:
 </p>
 <div class="code">
 $ td patch
 </div>
 <p>
 This will automatically generate a patch file for all your changes,
 and then open it in your preferred editor. 
 You can also generate a patch for only certain files and directories.
 To do that, set <code>PATCHSET</code>, like this:
 </p>
 <div class="code">
 # Only write a patch for README.txt and the files in site/
 $ PATCHSET="README.txt site/" td patch
 </div>
 <p>
 As you'll notice, the top of the patch file should have some email-style
 headers that look like this:
 </p>
 <div class="code">
 From: Jordan Bancino &lt;@jordan:bancino.net&gt;
 Date: Fri Jul 29 03:21:21 PM EDT 2022
 Subject: Document Patch Procedure
 </div>
 <p>
 As much information as possible should be filled out for you, such as
 the date. An attempt to fill out the <code>From</code> header was also
 made, but the information there can be made more accurate by setting
 <code>MXID</code> to your Matrix ID, and <code>DISPLAY_NAME</code> to
 your real name in your environment, or the <code>.env</code> file.
 The <code>Subject</code> should very briefly describe what the patch
 is about.
 </p>
 <p>
 You'll also notice these lines:
 </p>
 <div class="code">
 [ ] I have read the Telodendria Project developer certificiate of
    origin, and certify that I have permission to submit this patch
    under the conditions specified in it.
 </div>
 <p>
 This is a checkbox that tells me whether or not you actually have
 the rights to submit your patch, and that once you submit the patch,
 your code is bound by the Telodendria license. The full text of the
 developer certificate of origin is as follows:
 </p>
 <ol>
 <li>The contribution was created in whole or in part by me, and I have
 the right to submit it under the open source license of the Telodendria
 project; or</li>
 <li>The contribution is based upon a previous work that, to the best
 of my knowledge, is covered under an appropriate open-source license
 and I have the right under that license to submit that work with
 modifications, whether created in whole or in part by me, under the
 Telodendria project license; or</li>
 <li>The contribution was provided directly to me by some other person
 who certified (1), (2), or (3), and I have not modified it.</li>
 <li>I understand and agree that this project and the contribution are
 public and that a record of the contribution&mdash;including all
 personal information I submit with it&mdash;is maintained indefinitely
 and may be redistributed consistent with this project or the open-source
 licenses involved.</li>
 </ol>
 <p>
 After the headers, but before the checkbox, write a more thorough
 description of the patch and why it was created. Then, send the
 resulting patch file to <code>#telodendria-patches:bancino.net</code>,
 so it can be discussed and reviewed by the community.
 </p>
 <p>
 Try to keep your patches on topic&mdash;make one patch file per feature
 or bug fix being implemented. It is okay if your patches depend on previous
 patches, just indicate that in the patch. Note that it may take a while
 for patches to be committed, and some patches may not be committed at
 all. In either case, all sent patches are queued from the Matrix room into the
 <a href="/patches">public patch directory</a>, so they can be referenced easier
 in the future. If you want to reference a submitted patch in a Matrix message
 or email, it might be a good idea to link to it in the public patch directory.
 </p>
 <p>
 The public patch directory works as follows: when you send your patch to the
 Matrix room, it is downloaded by the <b>Telodendria</b> Bot and placed in the
 <code>ingress/</code> directory, named as the message ID. Then, it is 
 assigned a <b>Telodendria</b> patch ID and copied to the <code>p/</code>
 directory as just <code>${id}.patch</code>. This is a permanent link that will
 always reference your patch. Then, your patch is symlinked to the
 <code>queue/</code> directory. I have a script that automatically ingresses
 patches and queues them for me, and I'll use this to review patches.
 If your patch is accepted, the queue symlink will be moved to the
 <code>accepted/</code> directory and the patch is committed to the official
 CVS repository. If you patch is rejected for some reason, its symlink will
 be moved to the <code>rejected/</code> directory. Regardless of the state
 of your patch, it will always remain permalinked in the <code>p/</code>
 directory, and when it is accepted or rejected, <b>Telodendria</b> Bot will
 send a message.
 </p>
 <p>
 You're always welcome to inquire about rejected patches, and request they be
 reviewed again, or you can use them as a starting point for future patches.
 </p>
 <h2 id="resources">Resources</h2>
 <ul>
 <li><a target="_blank" href="/pub">Old <b>Telodendria</b> Versions</a></li>