diff --git a/docs/Process_CI.md b/docs/Process_CI.md index 77882212..5c70ed34 100644 --- a/docs/Process_CI.md +++ b/docs/Process_CI.md @@ -1,19 +1,14 @@ -# Build actions for developers and maintainers +# Automation for developers and maintainers -**Note**: Add ideas for process improvements as comments to the [Jira ticket](https://armbian.atlassian.net/browse/AR-2429). +Core automation for generating images for release are held at -Manual executing permissions are tied to [release manager](https://github.com/orgs/armbian/teams/release-manager) role within Armbian organization. Do you [want to help and take this role](https://calendly.com/armbian/office-hours)? -## Prepare build lists (anyone) +## Prepare build lists -[https://github.com/armbian/os](https://github.com/armbian/os) ### Recommended images -Recommended images on download pages -![Standard support images](images/standard-support-images.png) - -are defined via regular expression mapping file `exposed.map` : +Recommended images on download pages are defined via regular expression mapping file `exposed.map`: Example: @@ -21,11 +16,14 @@ Example: bananapim7/archive/Armbian_[0-9].*Bananapim7_noble_vendor_[0-9]*.[0-9]*.[0-9]*_gnome-kisak_desktop.img.xz bananapim7/archive/Armbian_[0-9].*Bananapim7_bookworm_vendor_[0-9]*.[0-9]*.[0-9]*_minimal.img.xz ``` + +![Standard support images](images/standard-support-images.png) + ### Build templates They have definitions on what kind of images we want to build - for section or for one specific board: -``` +``` yaml userpatches/targets-release-apps.template userpatches/targets-release-community-maintained.template userpatches/targets-release-nightly.template @@ -38,7 +36,7 @@ From those templates we are [autogenerating](https://github.com/armbian/os/blob/ Autogeneration is excluded for boards that are on blacklists: -``` +``` yaml userpatches/targets-automation.blacklist userpatches/targets-automation-nightly.blacklist ``` @@ -59,7 +57,10 @@ Example: khadas-edge2,legacy:vendor:,ENABLE_EXTENSIONS="image-output-oowow,v4l2loopback-dkms,mesa-vpu" ``` -## Prepare Standard Support images for release (release manager) +## Prepare Standard Support images for release + +???+ Info + Manual executing permissions are tied to [release manager role](/Process_Contribute/#release-manager). [![Build Standard Support Images](https://github.com/armbian/os/actions/workflows/complete-artifact-matrix-standard-support.yml/badge.svg)](https://github.com/armbian/os/actions/workflows/complete-artifact-matrix-standard-support.yml) diff --git a/docs/Process_Contribute.md b/docs/Process_Contribute.md index d841dc72..b338c2e4 100644 --- a/docs/Process_Contribute.md +++ b/docs/Process_Contribute.md @@ -1,6 +1,6 @@ # Collaborate on the project -## How? +## Overview 1. [Fork](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo) the project. 1. Make one or more well commented and clean commits to the repository. @@ -10,24 +10,60 @@ If it is a new feature request, do not start the coding first. Remember to [open If you are struggling, check [WEB](https://www.exchangecore.com/blog/contributing-concrete5-github) or [CLI](https://www.digitalocean.com/community/tutorials/how-to-create-a-pull-request-on-github) step-by-step guide on contributing. -## Where are the sources? +## Source code -Build script: + -[https://github.com/armbian/build](https://github.com/armbian/build) +## Adding a new board? -Documentation: +There are no detailed instructions on how to add a new board or even a whole new board family to the build script yet. However there are a few commits / pull requests that give clues how to achieve that like -[https://github.com/armbian/documentation](https://github.com/armbian/documentation) +- [https://github.com/armbian/build/pull/3176/files](https://github.com/armbian/build/pull/3176/files) +- [https://github.com/armbian/build/pull/3138/files](https://github.com/armbian/build/pull/3138/files) -Armbian-config tool: +## Board maintainer -[https://github.com/armbian/config](https://github.com/armbian/config) +If you are interested in being a maintainer please review [Board Support Rules](/User-Guide_Board-Support-Rules/). Then [apply here](https://forum.armbian.com/staffapplications/application/8-single-board-computer-maintainer/) and wait for acceptance. Once accepted you will be added to our infrastruture. For this reason we need [additional information](https://www.armbian.com/maintainer-registry/) to complete your registration process. -## Help with donations +!!! question "Requirements?" -If you find our project useful, then we’d really appreciate it if you’d consider contributing to the project however you can. Donating is the easiest way to help us – you can use PayPal and Bitcoin or you can buy us something from our Amazon.de wish list. + - You must have access to the hardware you applied to maintain + - You must have a Github ID which should be listed in the documentation + - You must have a forums account + - You must have an Jira account and keep track of issues filed for your board + - You must make sure [Armbian management](https://www.armbian.com/maintainer-registry/) has been informed of all of the above IDs for our documentation + - You should know Armbian basics like how to get an Armbian image run on your hardware and do basic debugging, ideally via serial console + - Knowledge in development, writing code and so on is optional but welcome -[https://www.armbian.com/donate/](https://www.armbian.com/donate/) +### Expectations -Thanks! +Maintainers must not necessarily be persons with development experience. They act as a intersection between end-users and the development team and serve the developers in best-effort manner. They are encouraged to answer basic/simple user questions (if possible, also best effort) without having to bother the development team. They are allowed to record bugs but are not allowed to escalate bugs. Team leaders do. + +Take note that it is still up to development team's discretion what gets attention since Armbian has to plan carefully how to spend its very limited resources. + +- You must participate in release process. Ideally you attend meetings related to releases. On that occasion you are given the chance to point out critical issues with your board. +- You must sign-off that device has been tested, is stable, and ready for release during release process. This basically means you test images that are getting prepared for release + +!!! question "What are we looking for?" + + - does the board boot to both CLI and Desktop? + - is the desktop usable? + - does USB work? (at all or partially) + - other things such as wireless, audio + +If something does not work, this is fine and normal. The important part is that it is documented and we get notified about the issues. Known problems should be placed into the Jira ticket and link placed to the board download page. While not required, you should have a build environment setup so you can build images with the most recent images and test them right away. Your feedback, either positive or negative, is very welcome. You are free to add comments to every commit and pull request. + +Ideally you have multiple microSD cards laying around to test regular updates on current releases and nightly without having to re-flash the same card every time to switch between branches. + +Alternatively you can use auto-built images - they are placed at the ever end of each board download pages under "Rolling releases". + +- You must provide "best effort" support in the forum. Do not let that wording intimidate you. This is not a complicated task. Regarding forums this can include things like answering obvious questions (for example by pointing to our documentation, ideally directly to the solution page), let the questioner know that additional information is needed for further debugging (e.g. request "armbianmonitor -u" output) or for upgrade issues, ask if they can recreate the issue with a fresh untouched image from: + +- You must provide "best effort" support in Jira. Review submitted issues for you board made by Armbian's contributors + +## Release manager + +This role has additional permimssion that allowes preparartion of images for release. + +Release managers: + \ No newline at end of file diff --git a/docs/Process_Merge-Policy.md b/docs/Process_Merge-Policy.md deleted file mode 100644 index e90785e8..00000000 --- a/docs/Process_Merge-Policy.md +++ /dev/null @@ -1,101 +0,0 @@ -# Merge Policy - -## Overview - -_Note: This document is a Work In Progress and is subject to change. Definitions may be relocated to a seperate document in the future._ - -This policy is targeted for Maintainers for Lead Maintainers who have commit access to `master` branch. This document describes the tags needed for different merge types. See Definitions. - -The types of code maintained fall into the following categories: - -* Kernel -* U-Boot -* Build scripts - -Kernel and U-Boot maintainers are usually grouped by SoC Architecture. - -Supported boards will have the most scrunity with code review. - -## U-Boot Patches - -- Standard contributors provide _tested-by_ submitter (`armbianmonitor -u` with a fresh build). -- SoC maintainer may submit a PR reviewed by of the lead SoC maintainer only. - -## Kernel Related Patches - -### legacy and current branches - -- DT changes reviewed by at least one person familiar with this SoC (lead maintainer or deputy), _tested-by_ the contributor who sends it (armbianmonitor). -- Trivial module activation doesn't matter. - -### dev/edge branches - -Constraints are at the discretion of the SoC mantainer. This builds are not expected to be stable. - -## Armbian Build Scripts - -This pertains to code used to build system images, OS configuration, and supporting packages (basically anything not u-boot or kernel source). - -### lib scripts - -* Requires at least one _Reviewed-by_. - -### Configuration - -#### board promotion - -Boards have different levels of commitment / support. EOL, CSC, WIP, Supported. To promote a board from WIP to Supported an Acked-by from a Lead Maintainer is required. - -#### kernel config - -* Changes in legacy & current kernel config should provide at least _tested-by_ with `armbianmonitor -u`. -* Changes in edge are at the discretion of maintainer. No constraints. - -#### kernel sources - -Change kernel source repos, branches, versions can be very disruptive to stable builds. Sufficient communication should occur stable changes. - -* U-Boot and kernel version bump for legacy and current requires _tested-by_ from Maintainers and/or testers on at least two different boards for the impacted platform. -* Kernel sources switch (legacy current) needs a discussion on forum or github or IRC and documented in PR and _Acked-by_ Lead Maintainer. These changes are risky and things can go terrible wrong here... -* edge source changes are at the discretion of the Lead Maintainer. -* Board family tweaks require at least _reviewed-by_. - -#### packages - -* minimum require _Acked-by_ - -## Definitions - -### Code Review Terms - -[click here for attribution to terms used below](https://lists.x.org/archives/xorg-devel/2009-October/003036.html) - -#### Signed-off-by - -Certifies that you wrote it or otherwise have the right to pass it on as a open-source patch. - -#### Acked-by - -If a person was not directly involved in the preparation or handling of a patch but wishes to signify and record their approval of it then they can arrange to have an Acked-by: line. Acked-by: does not necessarily indicate acknowledgement of the entire patch. - -#### Tested-by - -A Tested-by: tag indicates that the patch has been successfully tested (in some environment) by the person named. This tag informs maintainers that some testing has been performed, provides a means to locate testers for future patches, and ensures credit for the testers. - -#### Reviewed-by - -A Reviewed-by tag is a statement of opinion that the patch is an appropriate modification of the kernel without any remaining serious technical issues. Any interested reviewer (who has done the work) can offer a Reviewed-by tag for a patch. - -### Other - -#### Maintainer - -An Individual designated to moderate, support and make decisions for a codebase or component. There can be multiple maintainers assigned to any given thing. - -#### Lead Maintainer - -A more experienced maintainer that will decide on high-impact and stategic changes and have final say in disputes. A lead maintainer may share or designiate responsibility to some or all components within their domain of responsibility. - -#### SoC - -System on-a-Chip. diff --git a/docs/Release_Board-Maintainers.md b/docs/Release_Board-Maintainers.md index 5ef2e3de..980f1e6e 100644 --- a/docs/Release_Board-Maintainers.md +++ b/docs/Release_Board-Maintainers.md @@ -2,12 +2,40 @@ ## How to become a maintainer? -If you are interested in being a maintainer please review our documentation before applying: [Board Maintainers Procedures and Guidelines](https://docs.armbian.com/Board_Maintainers_Procedures_and_Guidelines/) +If you are interested in being a maintainer please review [Board Support Rules](/User-Guide_Board-Support-Rules/). Then [apply here](https://forum.armbian.com/staffapplications/application/8-single-board-computer-maintainer/) and wait for acceptance. Once accepted you will be added to our infrastruture. For this reason we need [additional information](https://www.armbian.com/maintainer-registry/) to complete your registration process. -Then, you can [apply here](https://forum.armbian.com/staffapplications/application/8-single-board-computer-maintainer/) and wait for acceptance. Once accepted you will be added to our various systems and asked to fill out the [Maintainer Registry Form](https://www.armbian.com/maintainer-registry/) to complete your registration process. +!!! question "Requirements?" -## Current Maintainers + - You must have access to the hardware you applied to maintain + - You must have a Github ID which should be listed in the documentation + - You must have a forums account + - You must have an Jira account and keep track of issues filed for your board + - You must make sure [Armbian management](https://www.armbian.com/maintainer-registry/) has been informed of all of the above IDs for our documentation + - You should know Armbian basics like how to get an Armbian image run on your hardware and do basic debugging, ideally via serial console + - Knowledge in development, writing code and so on is optional but welcome -https://www.armbian.com/authors/ +## Expectations -The authoritative list of `board.conf` can be found [here](https://github.com/armbian/build/tree/main/config/boards). +Maintainers must not necessarily be persons with development experience. They act as a intersection between end-users and the development team and serve the developers in best-effort manner. They are encouraged to answer basic/simple user questions (if possible, also best effort) without having to bother the development team. They are allowed to record bugs but are not allowed to escalate bugs. Team leaders do. + +Take note that it is still up to development team's discretion what gets attention since Armbian has to plan carefully how to spend its very limited resources. + +- You must participate in release process. Ideally you attend meetings related to releases. On that occasion you are given the chance to point out critical issues with your board. +- You must sign-off that device has been tested, is stable, and ready for release during release process. This basically means you test images that are getting prepared for release + +!!! question "What are we looking for?" + + - does the board boot to both CLI and Desktop? + - is the desktop usable? + - does USB work? (at all or partially) + - other things such as wireless, audio + +If something does not work, this is fine and normal. The important part is that it is documented and we get notified about the issues. Known problems should be placed into the Jira ticket and link placed to the board download page. While not required, you should have a build environment setup so you can build images with the most recent images and test them right away. Your feedback, either positive or negative, is very welcome. You are free to add comments to every commit and pull request. + +Ideally you have multiple microSD cards laying around to test regular updates on current releases and nightly without having to re-flash the same card every time to switch between branches. + +Alternatively you can use auto-built images - they are placed at the ever end of each board download pages under "Rolling releases". + +- You must provide "best effort" support in the forum. Do not let that wording intimidate you. This is not a complicated task. Regarding forums this can include things like answering obvious questions (for example by pointing to our documentation, ideally directly to the solution page), let the questioner know that additional information is needed for further debugging (e.g. request "armbianmonitor -u" output) or for upgrade issues, ask if they can recreate the issue with a fresh untouched image from: + +- You must provide "best effort" support in Jira. Review submitted issues for you board made by Armbian's contributors \ No newline at end of file diff --git a/docs/User-Guide_Board-Support-Rules.md b/docs/User-Guide_Board-Support-Rules.md index 160da94c..3acdcb7b 100644 --- a/docs/User-Guide_Board-Support-Rules.md +++ b/docs/User-Guide_Board-Support-Rules.md @@ -1,29 +1,34 @@ -# Support Definitions, Criteria and Relationships +# Board support Rules ## Overview -Support statuses: +Support definitions, criteria and relationships for: -- Standard support -- Staging -- Community maintained +- [Platinum Support](#platinum-support) +- [Standard support](#standard-support) +- [Community maintained](#community-maintained) +- [Staging](#) -## Gold and Platinum Support +## Platinum Support -Gold and Platinum support is reserved for business relationships with the Armbian project and is out of the scope of this document. Please [contact us](https://www.armbian.com/contact/) for more information. +Platinum support is reserved for business relationships with the Armbian project and is out of the scope of this document. + +### Contact us + +Please [contact Armbian](https://www.armbian.com/contact/) management for more information. ## Standard Support -### Benefits provided for a Standard Supported SBC +### Benefits * Armbian will publish and distribute "stable" images through its [mirror network](https://github.com/armbian/mirror) (behind automated closest mirror selection) * Armbian will publish and distribute "rolling" [images](https://github.com/armbian/os/releases/latest) (on GitHub and individual download page) -* best-effort support to SBC maintainer to assure compatiblity within the [Armbian Build Framework](https://github.com/armbian/build) +* best-effort support to SBC maintainer to assure compatibility within the [Armbian Build Framework](https://github.com/armbian/build) * best-effort team's unique expertise to assist maintainer with general challenges * best-effort [automated testing](https://github.com/armbian/os#latest-smoke-tests-results) for basic hardware functionality * best-effort compensation will be provided to maintainer from the "Armbian Community Fund" [[1]](https://github.com/sponsors/armbian) [[2]](https://liberapay.com/armbian) [[3]](https://forum.armbian.com/crowdfunding/) -### Criteria for Supported +### Requirements For a SBC to be considered supported: @@ -38,13 +43,13 @@ For a SBC to be considered supported: * maintainer should attend [developers meetings](https://forum.armbian.com/events/) held every Wednesday 7:00 PM CET * when whole support burden is carried by maintainer and Armbian team, it will be labelled as "Pro bono" -Additional Caveats: +???+ Info "Additional Caveats" -* if the burden placed on the maintainer and Armbian team is too high, [crowdfunding campaign](https://forum.armbian.com/crowdfunding/) success will decide support -* supported is **not** applied to a "board family" or group of related SBCs. It is per board -* a maintainer can support multiple devices but must satisfy all requirements above per SBC -* any individual can be a maintainer for a standard support SBC -* missed major release will result in immediate forfeit of "Armbian Standard support" status and demotion to "Community maintained" status unless Armbian team grants exemption + * if the burden placed on the maintainer and Armbian team is too high, [crowdfunding campaign](https://forum.armbian.com/crowdfunding/) success will decide support + * supported is **not** applied to a "board family" or group of related SBCs. It is per board + * a maintainer can support multiple devices but must satisfy all requirements above per SBC + * any individual can be a maintainer for a standard support SBC + * missed major release will result in immediate forfeit of "Armbian Standard support" status and demotion to "Community maintained" status unless Armbian team grants exemption ## Community maintained @@ -52,35 +57,36 @@ Community maintained devices are not under active supervision or development. Su Community maintained SBCs are exclusively supported by the community. -### Caveats for Community maintained SBC +### Benefits * Armbian will publish and distribute images through its [mirror network](https://github.com/armbian/mirror) -* Armbian will publish and distribute rolling [images](https://github.com/armbian/os/releases/latest) +* Armbian will publish and distribute daily rolling [images](https://github.com/armbian/os/releases/latest) * periodic packages are built and published into Armbian's apt repository * images are untested and Armbian team won't respond on troubles or apply any fixes. -### Requirements for Community Support +### Requirements * patch or component does not break Armbian Build Framework * patch or component does not break build of supported boards or other CSCs * pull requests needs community review. Armbian team will not review any code related to community supported SBC * generally considered to "work most of the time" -* generally considered to recieve periodic maintenance from community and upstream +* generally considered to receive periodic maintenance from community and upstream -## Staging - Work in progress +## Staging -WIP status is for when a maintainer has commited to a SBC, but is not ready to ship stable images. +Work in progress (WIP) status is for when a maintainer has committed to a SBC, but is not ready to ship stable images. -Benefits of Community Supported SBCs apply to WIP. +### Benefits -### Additional Benefits provided for a Staging status +All benefits of Community Supported SBCs apply to Staging as well. * periodic / nightly CLI images are published by Armbian -* best-effort support to SBC maintainer to assure compatiblity within the [Armbian Build Framework](https://github.com/armbian/build) +* best-effort support to SBC maintainer to assure compatibility within the [Armbian Build Framework](https://github.com/armbian/build) * best-effort team's unique expertise to assist maintainer with general challenges * eligible for promotion to Standard Support -### Criteria for WIP status +### Requirements * must satisfy standard support criteria * must show active development +* must compile successfully most of the time diff --git a/mkdocs.yml b/mkdocs.yml index 6870beff..7a83f244 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -116,11 +116,9 @@ nav: - 'Build Preparation' : 'Developer-Guide_Build-Preparation.md' - 'User Configurations' : 'Developer-Guide_User-Configurations.md' - 'Extensions Hooks' : 'Developer-Guide_Extensions-Hooks.md' - - 'Board Maintainers' : 'Release_Board-Maintainers.md' - 'Building with Multipass' : 'Developer-Guide_Building-with-Multipass.md' - 'Build Options' : 'Developer-Guide_Build-Options.md' - 'Building with Docker' : 'Developer-Guide_Building-with-Docker.md' - - 'Adding Board Family' : 'Developer-Guide_Adding-Board-Family.md' - 'Extensions' : 'Developer-Guide_Extensions.md' - 'ARMBIAN COMMUNITY' : @@ -130,11 +128,6 @@ nav: - 'CONTRIBUTE' : - 'Contribute' : 'Process_Contribute.md' - - 'Managing_Workflow' : 'Process_Managing_Workflow.md' - - 'Armbian Task Tracking' : 'Process_Armbian-Task-Tracking.md' - - 'Merge Policy' : 'Process_Merge-Policy.md' + - 'Automation' : 'Process_CI.md' - 'Board Support Rules' : 'User-Guide_Board-Support-Rules.md' - - 'Maintainers_Procedures_and_Guidelines' : 'Board_Maintainers_Procedures_and_Guidelines.md' - - 'CI' : 'Process_CI.md' - - 'Review_Procedures_and_Guidelines' : 'Development-Code_Review_Procedures_and_Guidelines.md'