plate/telodendria
1
0
Fork 0
forked from lda/telodendria
Code Pull requests Activity Actions

Move contributing guide to a man page.

Browse source
This commit is contained in:
Jordan Bancino 2022-09-23 08:54:47 -04:00
parent 55967c2d75
commit 5178fd2d21
2 changed files with 247 additions and 248 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

244
docs/contributing.7
View file

@ -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.

251
site/index.html
View file

@ -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.8.html">telodendria(8)</a> - Command line</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 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>