81 lines
3.1 KiB
Markdown
81 lines
3.1 KiB
Markdown
|
# the contributor's handbook
|
||
|
|
|
||
|
|
expected details on development workflows? see [the developer's handbook](developing.md)
|
||
|
|
|
||
|
|
## which forge do i use?
|
||
|
|
|
||
|
|
as at the time of writing this documentation, i am actively using both
|
||
|
|
<https://github.com/markjoshwel/surplus> and <https://forge.joshwel.co/mark/surplus>
|
||
|
|
|
||
|
|
use whatever is more comfortable to you. do you not like microsoft and/or have moved away from github?
|
||
|
|
feel free to use <https://forge.joshwel.co>. don't want to make an account for either? did the forge
|
||
|
|
implode and is down? okay! mail in a git patch at <mark@joshwel.co>
|
||
|
|
|
||
|
|
## git workflow
|
||
|
|
|
||
|
|
1. fork the repository and branch off from the `future` branch,
|
||
|
|
or `main` if not available
|
||
|
|
2. make and commit your changes!
|
||
|
|
3. pull in any changes from upstream, and resolve any conflicts, if any
|
||
|
|
4. if needed, **commit your copyright waiver** (_see [waiving copyright](#waiving-copyright)_)
|
||
|
|
5. submit a pull request (_or mail in a patch_)
|
||
|
|
|
||
|
|
### waiving copyright
|
||
|
|
|
||
|
|
!!! danger "Warning"
|
||
|
|
this section is a **must** to follow if you have modified **any** unlicenced code:
|
||
|
|
|
||
|
|
- top-level surplus files (`releaser.py`, etc)
|
||
|
|
- surplus (`src/surplus`)
|
||
|
|
- surplus Documentation (`docs/`)
|
||
|
|
- surplus on wheels (`src/surplus-on-wheels`)
|
||
|
|
- surplus on wheels: Telegram Bridge (`src/spow-telegram-bridge`)
|
||
|
|
|
||
|
|
!!! info
|
||
|
|
the command to create an empty commit is `git commit --allow-empty`
|
||
|
|
|
||
|
|
when contributing your first changes, please include an empty commit for a copyright
|
||
|
|
waiver using the following message (replace `Your Name` with your name or username):
|
||
|
|
|
||
|
|
```text
|
||
|
|
Your Name Copyright Waiver
|
||
|
|
|
||
|
|
I dedicate any and all copyright interest in this software to the
|
||
|
|
public domain. I make this dedication for the benefit of the public at
|
||
|
|
large and to the detriment of my heirs and successors. I intend this
|
||
|
|
dedication to be an overt act of relinquishment in perpetuity of all
|
||
|
|
present and future rights to this software under copyright law.
|
||
|
|
|
||
|
|
To the best of my knowledge and belief, my contributions are either
|
||
|
|
originally authored by me or are derived from prior works which I have
|
||
|
|
verified are also in the public domain and are not subject to claims
|
||
|
|
of copyright by other parties.
|
||
|
|
|
||
|
|
To the best of my knowledge and belief, no individual, business,
|
||
|
|
organization, government, or other entity has any copyright interest
|
||
|
|
in my contributions, and I affirm that I will not make contributions
|
||
|
|
that are otherwise encumbered.
|
||
|
|
```
|
||
|
|
|
||
|
|
(from <https://unlicense.org/WAIVER>)
|
||
|
|
|
||
|
|
for documentation contributors, if you have contributed a
|
||
|
|
[legally significant](https://www.gnu.org/prep/maintain/maintain.html#Legally-Significant) or have
|
||
|
|
repeatedly commited multiple small changes, waive your copyright with the CC0 deed
|
||
|
|
(replace `Your Name` with your name or username):
|
||
|
|
|
||
|
|
```text
|
||
|
|
Your Name Copyright Waiver
|
||
|
|
|
||
|
|
The person who associated a work with this deed has dedicated the work to
|
||
|
|
the public domain by waiving all of his or her rights to the work worldwide
|
||
|
|
under copyright law, including all related and neighboring rights, to the
|
||
|
|
extent allowed by law.
|
||
|
|
```
|
||
|
|
|
||
|
|
(from <https://creativecommons.org/publicdomain/zero/1.0/>)
|
||
|
|
|
||
|
|
## reporting incorrect output
|
||
|
|
|
||
|
|
TODO
|