stagex/CONTRIBUTING.md

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.

Prepopulate your local registry

$ 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

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.

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):

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 | ircs://irc.oftc.net:6697#stagex

For discussions around issues/bugs and features, you can use Codeberg issues and PRs tracking system.