From a53a435f4479382c5b2f5381b7d253ca316ba28e Mon Sep 17 00:00:00 2001 From: ConYel Date: Fri, 15 Mar 2024 23:38:05 +0100 Subject: [PATCH 1/2] fear: add CONTRIBUTING.md --- CONTRIBUTING.md | 193 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3757741 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,193 @@ +![[Stagex]](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:/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 + + +## 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 + + +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. + From 1f46e90ee09762ecd82d5b40195751c1a4eac883 Mon Sep 17 00:00:00 2001 From: ConYel Date: Sat, 23 Mar 2024 11:23:59 +0100 Subject: [PATCH 2/2] chore: review changes v1 --- CONTRIBUTING.md | 89 ++++++++++++++++++------------------------------- 1 file changed, 32 insertions(+), 57 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3757741..6f72446 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,6 +56,13 @@ $ sh ./src/setup-debian-12.sh Stagex uses a Makefile to build everything. +Populate your local registry by building from scratch +```shell +$ make all +``` +| +OR +| Prepopulate your local registry ```shell $ make preseed @@ -63,7 +70,7 @@ $ rm -rf ./out/sxctl $ make sxctl ``` -Find if there is a relevant package that you can you as a boilerplate for the +Find if there is a relevant package that you can use as a boilerplate for the new addition. ``` cp -R packages/python packages/cython @@ -73,16 +80,31 @@ vim packages/cython/Containerfile # https://git.alpinelinux.org/aports/tree/main/cython/APKBUILD make gen-make make cython -make digests # maybe this is wrong!!! - +make digests ``` -Then you can commit and push your package and open a PR. +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: +``` +package=somepackage; rm -rf out{,2}/${package}; make NOCACHE=1 ${package}; mv out/${package} out2/; 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 @@ -101,17 +123,15 @@ 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). +PRs will be approved by a [maintainer] listed in [`MAINTAINERS`](MAINTAINERS). 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. +"[CI:DOCS]". ### Describe your Changes in Commit Messages @@ -126,55 +146,10 @@ 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 +### 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`.