fear: add CONTRIBUTING.md
This commit is contained in:
ConYel
parent
c6d8c851df
commit
a53a435f44
1 changed files with 193 additions and 0 deletions
193
CONTRIBUTING.md
Normal file
193
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,193 @@
|
|||
![[Stage<sup>x</sup>]](https://codeberg.org/repo-avatars/02eca12ad01b1b867ca7708117645b4d9791a7f7a30abd6d8e1dc20900f7b0d7)
|
||||
# Contributing to Stagex
|
||||
|
||||
We'd be happy to have you join the community!
|
||||
Below are the steps and processes that we follow.
|
||||
|
||||
## Topics
|
||||
|
||||
* [Reporting Issues](#reporting-issues)
|
||||
* [Working On Issues](#working-on-issues)
|
||||
* [Contributing to Stagex as package maintainer](#contributing-to-stagex-as-package-maintainer)
|
||||
* [Helpful one liners](#helpful-one-liners)
|
||||
* [Submitting Pull Requests](#submitting-pull-requests)
|
||||
* [Communications](#communications)
|
||||
|
||||
## Reporting Issues
|
||||
|
||||
Before reporting an issue, check our backlog of
|
||||
[open issues](https://codeberg.org/stagex/stagex/issues)
|
||||
to see if someone else has already reported it. If so, feel free to add
|
||||
your scenario, or additional information, to the discussion. Or simply
|
||||
"subscribe" to it to be notified when it is updated.
|
||||
If you find a new issue with the project we'd love to hear about it! The most
|
||||
important aspect of a bug report is that it includes enough information for
|
||||
us to reproduce it.
|
||||
Please don't include any private/sensitive information in your issue!
|
||||
|
||||
## Working On Issues
|
||||
|
||||
Once you have decided to contribute to Stagex by working on an issue, check our
|
||||
backlog of [open issues](https://codeberg.org/stagex/stagex/issues) looking
|
||||
for any that do not have an "In Progress" label attached to it. Often issues
|
||||
will be assigned to someone, to be worked on at a later time.
|
||||
|
||||
## Contributing to Stagex as package maintainer
|
||||
|
||||
This section describes how to start a contribution to Stagex.
|
||||
These instructions are geared towards using a Linux development machine,
|
||||
preferably Debian, which is required for setting up your development tools.
|
||||
|
||||
### Fork and clone Stagex
|
||||
|
||||
First you need to fork this project on Codeberg.
|
||||
Then clone your fork locally:
|
||||
```shell
|
||||
$ git clone git@codeberg.com:<you>/stagex
|
||||
$ cd stagex
|
||||
```
|
||||
|
||||
### Prepare your environment
|
||||
```
|
||||
$ sh ./src/setup-debian-12.sh
|
||||
```
|
||||
|
||||
### Deal with make
|
||||
|
||||
Stagex uses a Makefile to build everything.
|
||||
|
||||
Prepopulate your local registry
|
||||
```shell
|
||||
$ make preseed
|
||||
$ rm -rf ./out/sxctl
|
||||
$ make sxctl
|
||||
```
|
||||
|
||||
Find if there is a relevant package that you can you as a boilerplate for the
|
||||
new addition.
|
||||
```
|
||||
cp -R packages/python packages/cython
|
||||
vim packages/cython/Containerfile
|
||||
# fix SRC_FILE, SRC_HASH, SRC_URL etc manually
|
||||
# incorporate anything relevant from Alpines build(){ block } for {package}
|
||||
# https://git.alpinelinux.org/aports/tree/main/cython/APKBUILD
|
||||
make gen-make
|
||||
make cython
|
||||
make digests # maybe this is wrong!!!
|
||||
|
||||
```
|
||||
|
||||
Then you can commit and push your package and open a PR.
|
||||
IMPORTANT: the PR should be just the `Containerfile`, and the added block for
|
||||
the package you are contributing in `packages.mk`
|
||||
|
||||
## Helpful one liners
|
||||
<add one liners >
|
||||
|
||||
## Submitting Pull Requests
|
||||
|
||||
No Pull Request (PR) is too small! Typos, additional comments in the code,
|
||||
new test cases, bug fixes, new features, more documentation, ... it's all
|
||||
welcome!
|
||||
|
||||
While bug fixes can first be identified via an "issue", that is not required.
|
||||
It's ok to just open up a PR with the fix, but make sure you include the same
|
||||
information you would have included in an issue - like how to reproduce it.
|
||||
|
||||
PRs for new features should include some background on what use cases the
|
||||
new code is trying to address. When possible and when it makes sense, try to break-up
|
||||
larger PRs into smaller ones - it's easier to review smaller
|
||||
code changes. But only if those smaller ones make sense as stand-alone PRs.
|
||||
|
||||
Regardless of the type of PR, all PRs should include:
|
||||
* well documented code changes.
|
||||
*
|
||||
|
||||
PRs that fix issues should include a reference like `Closes #XXXX` in the
|
||||
commit message so that Codeberg will automatically close the referenced issue
|
||||
when the PR is merged.
|
||||
|
||||
PRs will be approved by an [approver][owners] listed in [`OWNERS`](OWNERS).
|
||||
|
||||
In case you're only changing docs, make sure to prefix the PR title with
|
||||
"[CI:DOCS]". That will prevent functional tests from running and save time and
|
||||
energy.
|
||||
|
||||
### Describe your Changes in Commit Messages
|
||||
|
||||
Describe your problem. Whether your patch is a one-line bug fix or 5000 lines
|
||||
of a new feature, there must be an underlying problem that motivated you to do
|
||||
this work. Convince the reviewer that there is a problem worth fixing and that
|
||||
it makes sense for them to read past the first paragraph.
|
||||
|
||||
Describe user-visible impact. Straight up crashes and lockups are pretty
|
||||
convincing, but not all bugs are that blatant. Even if the problem was spotted
|
||||
during code review, describe the impact you think it can have on users. Keep in
|
||||
mind that the majority of users run packages provided by distributions, so
|
||||
include anything that could help route your change downstream.
|
||||
|
||||
### Sign your PRs
|
||||
|
||||
The sign-off is a line at the end of the explanation for the patch. Your
|
||||
signature certifies that you wrote the patch or otherwise have the right to pass
|
||||
it on as an open-source patch. The rules are simple: if you can certify
|
||||
the below (from [developercertificate.org](https://developercertificate.org/)):
|
||||
|
||||
```
|
||||
Developer Certificate of Origin
|
||||
Version 1.1
|
||||
|
||||
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
|
||||
660 York Street, Suite 102,
|
||||
San Francisco, CA 94110 USA
|
||||
|
||||
Everyone is permitted to copy and distribute verbatim copies of this
|
||||
license document, but changing it is not allowed.
|
||||
|
||||
Developer's Certificate of Origin 1.1
|
||||
|
||||
By making a contribution to this project, I certify that:
|
||||
|
||||
(a) The contribution was created in whole or in part by me and I
|
||||
have the right to submit it under the open source license
|
||||
indicated in the file; or
|
||||
|
||||
(b) The contribution is based upon 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 same open source license (unless I am
|
||||
permitted to submit under a different license), as indicated
|
||||
in the file; or
|
||||
|
||||
(c) The contribution was provided directly to me by some other
|
||||
person who certified (a), (b) or (c) and I have not modified
|
||||
it.
|
||||
|
||||
(d) I understand and agree that this project and the contribution
|
||||
are public and that a record of the contribution (including all
|
||||
personal information I submit with it, including my sign-off) is
|
||||
maintained indefinitely and may be redistributed consistent with
|
||||
this project or the open source license(s) involved.
|
||||
```
|
||||
|
||||
Then you just add a line to every git commit message:
|
||||
|
||||
Signed-off-by: Joe Smith <joe.smith@email.com>
|
||||
|
||||
|
||||
If you set your `user.name` and `user.email` git configs, you can sign your
|
||||
commit automatically with `git commit -s`.
|
||||
|
||||
|
||||
## Communications
|
||||
|
||||
For general questions and discussion, please use the
|
||||
[matrix://#stagex:matrix.org](https://matrix.to/#/#stagex:matrix.org) | [ircs://irc.oftc.net:6697#stagex](https://webchat.oftc.net/?channels=stagex&uio=MT11bmRlZmluZWQmMTE9MTk14d)
|
||||
|
||||
For discussions around issues/bugs and features, you can use Codeberg
|
||||
[issues](https://codeberg.org/stagex/stagex/issues)
|
||||
and
|
||||
[PRs](https://codeberg.org/stagex/stagex/pulls)
|
||||
tracking system.
|
||||
|
||||
Loading…
Reference in a new issue