Levitating/Telodendria
1
0
Fork 0
forked from Telodendria/Telodendria
Code Pull requests Activity

Add contributing documentation.

Browse source
This commit is contained in:
Jordan Bancino 2023-09-09 16:50:38 -04:00
parent 9e8523d92e
commit 7a091c5b93
4 changed files with 196 additions and 269 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
.gitea/pull_request_template.md Normal file
View file

@ -0,0 +1,25 @@
---
Please review the developer certificate of origin:
1. 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
1. 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
1. The contribution was provided directly to me by some other person
who certified (1), (2), or (3), and I have not modified it.
1. I understand and agree that this project and the contribution are
made public and that a record of the contribution—including all
personal information I submit with it—is maintained indefinitely
and may be redistributed consistent with this project or the open
source licenses involved.
- [ ] I have read the Telodendria Project development certificate of
origin, and I certify that I have permission to submit this patch
under the conditions specified in it.

161
docs/CONTRIBUTING.md Normal file
View file

@ -0,0 +1,161 @@
# Contributing
Telodendria is a fully open source project. As such, it welcomes
contributions. There are many ways you can contribute, and any way you
can is greatly appreciated. This document details the ways you can
contribute, and how to go about contributing.
## Sponsoring Telodendria
If you would like to sponsor Telodendria, see the
[Sponsorship](../README.md#sponsorship) section on the main project
page. Donations of any size are greatly appreciated.
## Reporting Issues
An important way to get involved is to just report issues you find with
Telodendria during experimentation or normal use. To report an issue,
go to [Issues](/Telodendria/telodendria/issues) →
[New Issue](/Telodendria/telodendria/issues/new) and follow the
instructions.
> **Note:** GitHub issues are not accepted. Issues may only be
> submitted to the official [Gitea](https://git.telodendria.io)
> instance.
### Feature Requests
Feature requests are allowed, but note that they are low-priority in
comparison to existing issues and features. That being said, don't
hesitate to submit feature requests. Just select the "Feature Request"
option when submitting an issue.
## Developing
If you want to write code for Telodendria, either to fix an issue or
add a new feature, you're in the right place. Please follow all the
guidelines in this document to ensure the contribution workflow goes
as smoothly as possible.
### Who can develop Telodendria?
Everyone is welcome to contribute code to Telodendria, provided that
they are willing to license their contributions under the same license
as the project itself.
The primary language used to write Telodendria code is ANSI C. Other
languages you'll find in the Telodendria repository include shell
scripts, `mdoc`, a little bit of HTML and CSS, and `Makefiles`.
Experience with any of these is preferred, but if you want to use
Telodendria to learn, that's okay too! Telodendria's code base should
hopefully be a good learning tool, and if you are serious about
submitting quality work, we'll guide you through the process and
offer suggestions.
### What do I need?
You'll need a couple of things to develop Telodendria:
- A Unix-like operating system that provides standard POSIX behavior,
or the Windows Subsystem for Linux (WSL), Cygwin, or Msys2 if you are
running Windows.
- A C compiler capable of compiling ANSI C89 code (pretty much all of
them do—pick your favorite, and if you find it doesn't work,
open an issue!).
- `make` for building the project.
- `git` for managing your changes.
Optionally, you may also find these tools helpful:
- `indent` for formatting code.
- `valgrind` for debugging particularly nasty issues.
### Getting The Code
Telodendria is developed using Git. The easiest way to contribute
changes is to fork the main repository, and then creating a pull
request to ask us to pull your changes into our repo.
1. If you don't have an account on the
[Gitea instance](https://git.telodendria.io), create one and sign in.
1. Fork this repository.
1. In your development environment, clone your fork:
```shell
git clone https://git.telodendria.io/[YOUR_USERNAME]/telodendria.git
cd telodendria
```
Please base your changes on the `master` branch. If you need help
getting started with Git, that is beyond the scope of this
document, but you can find many good tutorials on the web.
### Building & Running
Telodendria uses the `make` build system.
**TODO:** Update this section before #19 is closed. Provide quick
make, run, and install directions (maybe just redirect to Porting for
install directions), then list all the `make` recipes. Shouldn't be
as many as were in `td`.
### Pull Requests
> **Note:** Telodendria does not accept GitHub pull requests at this
> time. Please submit your pull requests via Gitea.
Telodendria follows the standard pull request procedures. Once you have
made your changes, committed them, and pushed to your fork, you should
be able to open a pull request on the main repository. When you do, you
will be prompted to write a description
### 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.
- All function, enumeration, structure, and header names are
`CamelCase`. This is preferred to `snake_case` because it is more
compact.
- All variable names are `lowerCamelCase`. This is preferred to
`snake_case` because it is more compact. One exception to this rule is
if a variable name, such as a member of a struct, directly represents
a JSON key in an object specified by the Matrix specification, which
may be in `snake_case`.
- 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, unless
the enumeration or structure is intended to be made fully public.
- 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.
- 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.
- Anywhere that C allows curly braces to be optional, there still must
be curly braces. This makes it easier to read the code by making it
less ambiguous, and it makes it easier to add on to the code later.
As far as actually formatting the code goes, such as where to put
brackets, and whether or not to use tabs or spaces, use `indent` to
take care of that. The repository contains a `.indent.pro` that should
automatically be loaded by `indent` to set the correct rules. If you
don't have a working `indent`, then just indicate in your pull
request that I should run my `indent` on the code.
### Documentation
This project places a strong emphasis on documentation. Well-documented
code is fundamental to a successful project, so when you are writing
code, please also make sure that it is documented appropriately.
- If you are adding a header, make sure you add the necessary comments
detailing the header and the functions in it.
- If you are adding a function, make sure you add the necessary
comments to the appropriate header.
If your pull request does not also include proper documentation, it
will likely be rejected.

11
docs/user/install.md
View file

@ -48,4 +48,13 @@ binaries.
## From Source
**TODO:** Update this section before #19 is closed.
If you would like to build Telodendria from source, you can download
the latest release code from the
[Releases](/Telodendria/telodendria/releases) page. After extracting
the tarball, read
[Contributing → Developing → Building & Running](../CONTRIBUTING#building-and-running)
for details on how to build Telodendria.
If all goes well, you will find the server binary in the `build/`
directory. If an error occured, and you didn't modify the code,
please open an issue.

268
man/man7/telodendria-contributing.7
View file

@ -1,268 +0,0 @@
.Dd $Mdocdate: March 10 2023 $
.Dt TELODENDRIA-CONTRIBUTING 7
.Os Telodendria Project
.Sh NAME
.Nm telodendria-contributing
.Nd Guide to contributing to the Telodendria project.
.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. 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 1 ,
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 1 ,
but the information there can be modifed as necessary. Consult the manual
for
.Xr td 1
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 using
.Xr send-patch 1 .
.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.
.Pp
This project places a strong emphasis on documentation. Well-documented
code is fundamental to a successful project, so when you are writing code,
please also make sure it is documented appropriately.
.Bl -bullet
.It
If you are adding a header, make sure you add a man page that documents
all the functions in the header.
.It
If you're adding a function, make sure you add documentation for it
to the appropriate man page for the header that your function resides
in. Do note that you do not have to document static functions, only
public API functions.
.El
.Pp
If your patch does not also include proper documentation, it will
likely be rejected.