forked from Telodendria/Telodendria
Add contributing documentation.
This commit is contained in:
parent
9e8523d92e
commit
7a091c5b93
4 changed files with 196 additions and 269 deletions
25
.gitea/pull_request_template.md
Normal file
25
.gitea/pull_request_template.md
Normal 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
161
docs/CONTRIBUTING.md
Normal 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.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in a new issue