6 KiB
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
- Working On Issues
- Contributing to Stagex as package maintainer
- Helpful one liners
- Submitting Pull Requests
- Communications
Reporting Issues
Before reporting an issue, check our backlog of open 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 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:
$ 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.
Populate your local registry by building from scratch
$ make all
| OR | Prepopulate your docker local registry
$ make preseed
$ rm -rf ./out/sxctl
$ make sxctl
Find if there is a relevant package that you can use 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 Alpine's build(){ block } for {package}
# https://git.alpinelinux.org/aports/tree/main/cython/APKBUILD
make gen-make
make cython
make digests.txt
Then you can commit {signed} 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
<--author: Lance R. Vick -->
- see contents of a package:
package=somepackage tar -tvf $(find out/${package} -type f -printf '%s %p\n' | sort -nr | head -n1 | awk '{ print $2 }') | less
- test package for reproducibility:
mkdir out2;
package=somepackage; rm -rf out{,2}/${package}; make NOCACHE=1 ${package}; mv out/${package} out2/${package}; make NOCACHE=1 ${package}; diffoscope $(find out*/${package} -type f -printf '%s %p\n' | sort -nr | head -n2 | awk '{ print $2 }' | tr '\n' ' ')
- make svg graph of dependency tree for a single package
package=somepackage; make -Bnd ${package} | make2graph | dot -Tsvg -o ${package}-graph.svg
<--author: Lance R. Vick -->
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, ... all kinds of contribution are 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 a [maintainer] listed in MAINTAINERS.
In case you're only changing docs, make sure to prefix the PR title with "[CI:DOCS]".
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 commits
Your signature certifies that you wrote the patch or otherwise have the right to pass it on as an open-source patch.
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 | ircs://irc.oftc.net:6697#stagex
For discussions around issues/bugs and features, you can use Codeberg issues and PRs tracking system.