From 57787e72f5d76c44b551ffb95942de641bca52f3 Mon Sep 17 00:00:00 2001 From: CXM <16154023+littlecxm@users.noreply.github.com> Date: Thu, 7 Apr 2022 07:10:58 +0800 Subject: [PATCH] chore(readme): fix readme docs (#3631) * chore(readme): fix readme docs * chore(readme): fix discord link * chore: readme * chore(readme): fix jira link --- .github/CONTRIBUTING.md | 28 +++++++ README.md | 159 ++++++++++++++++------------------------ 2 files changed, 93 insertions(+), 94 deletions(-) create mode 100644 .github/CONTRIBUTING.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 000000000..fada0fee8 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,28 @@ +# How to contribute + +## Getting started + +- Fork the repository on GitHub +- Read the README.md for build instructions + +## Issue + +Reporting bugs is one of the best ways to contribute. However, a good bug report has some very specific qualities, so try to recreate it with a clean build framework clone. Then search for [existing and closed issues](https://github.com/armbian/build/issues). If you don't find it there, [open a new issue](https://github.com/armbian/build/issues/new). + +## Adding a new feature + +You are welcome to suggest or contribute directly to the code with a pull request. In case your proposed changes are large, remember to discuss them prior to development. + +## Join development + +Join regulars on their active missions, start maintaining any part of the code: patches, drivers or scripted applications like [armbian-config](https://github.com/armbian/config), address [community wishes](https://github.com/armbian/build/issues), + +## Additional information + +- [Build parameters and advanced build options](https://docs.armbian.com/Developer-Guide_Build-Options/), +- [Make use of user defined configurations](https://docs.armbian.com/Developer-Guide_User-Configurations/), +- [Docker](https://docs.armbian.com/Developer-Guide_Building-with-Docker/) and [Vagrant](https://docs.armbian.com/Developer-Guide_Using-Vagrant/) building guides, +- Engage in [Armbian build framework forums](https://forum.armbian.com/forum/4-development/), +- Check [Jira](https://armbian.atlassian.net/browse/AR) project management application status, +- Make use of central project [search engine](https://www.armbian.com/search), +- Browse [IRC channel logs](http://irc.armbian.com) or interact at #armbian on [Libera](https://libera.chat/). diff --git a/README.md b/README.md index 617d33232..e76ee81b4 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,76 @@ -

Armbian logo
-build framework

- -

 

+

+ + Armbian logo +
+ armbian build framework
+

[![GitHub last commit (branch)](https://img.shields.io/github/last-commit/armbian/build/master)](https://github.com/armbian/build/commits) [![GitHub Workflow Status](https://img.shields.io/github/workflow/status/armbian/build/Build?label=build%20train)](https://github.com/armbian/build/actions/workflows/build-train.yml) [![Twitter Follow](https://img.shields.io/twitter/follow/armbian?style=flat-square)](https://twitter.com/intent/follow?screen_name=armbian) +[![Join the Discord](https://img.shields.io/discord/854735915313659944.svg?color=7289da&label=Discord%20&logo=discord)](https://discord.com/invite/gNJ2fPZKvc) [![Become a patron](https://img.shields.io/liberapay/patrons/armbian.svg?logo=liberapay)](https://liberapay.com/armbian) ## Table of contents - [What this project does?](#what-this-project-does) -- [What do you need to get started?](#what-do-you-need-to-get-started) -- [How to build an image or a kernel?](#how-to-build-an-image-or-a-kernel) -- [Build parameter examples](#build-parameter-examples) +- [Getting started](#getting-started) - [Compare with industry standards](#compare-with-industry-standards) -- [Where to download prebuilt images?](#where-to-download-prebuilt-images) -- [Additional information](#additional-information) -- [Build framework overview](#build-framework-overview) +- [Download prebuilt images](#download-prebuilt-images) +- [Project structure](#project-structure) +- [Contribution](#contribution) - [Support](#support) -- [Contribute](#contribute) -- [Social](#social) -- [Credits](#credits) +- [Contact](#contact) +- [Contributors](#contributors) - [Sponsors](#sponsors) - -

 

- +- [License](#license) ## What this project does? -- builds custom Linux optimized for [single board computers](https://www.armbian.com/download/), -- covers filesystem generation, low-level control software, kernel image compilation and bootloader compilation, -- provides a consistent user experience by keeping system standards across different platforms. +- Builds custom Linux optimized for [single board computers(SBCs)](https://en.wikipedia.org/wiki/Single-board_computer). +- Including filesystem generation, low-level control software, kernel image compilation and bootloader compilation. +- Provides a consistent user experience by keeping system standards across different platforms. -

 

+## Getting started -## What do you need to get started? +### Prepare your environment - x64 / aarch64 machine with at least 2GB of memory and ~35GB of disk space for a VM, container or native OS, - Ubuntu Jammy 22.04 x64 / aarch64 for native building or any [Docker](https://docs.armbian.com/Developer-Guide_Building-with-Docker/) capable x64 / aarch64 Linux for containerised, -- superuser rights (configured sudo or root access). +- Superuser rights (configured sudo or root access). -

⇧

+### Simply start with the build script -## How to build an image or a kernel? - -```text +```bash apt-get -y install git git clone https://github.com/armbian/build cd build ./compile.sh ``` + Armbian logo -- will prepare the workspace by installing necessary dependencies and sources -- it guides through the process until either a kernel package set or a ready-to-use image for a SDcard is created -

⇧

+- Interactive graphical interface. +- The workspace will be prepared by installing the necessary dependencies and sources. +- It guides the entire process until a kernel package or ready-to-use image of the SD card is created. -## Build parameter examples +### Build parameter examples Show work in progress areas in interactive mode: -```text +```bash ./compile.sh EXPERT="yes" ``` Run build framework inside Docker container: -```text +```bash ./compile.sh docker ``` Build minimal CLI Armbian Focal image for Orangepi Zero. Use modern kernel and write image to the SD card: -```text +```bash ./compile.sh \ BOARD=orangepizero \ BRANCH=current \ @@ -87,8 +84,6 @@ CARD_DEVICE="/dev/sda" [Build parameters, advanced build options, user defined configuration, build with Docker?](#additional-information) -

⇧

- ## Compare with industry standards Check similarity, advantages and disadvantages compared with leading industry standard build software. @@ -105,31 +100,13 @@ Function | Armbian | Yocto | Buildroot | | Getting started | quick | very slow | slow | | Cross compilation | yes | yes | yes | -

⇧

+## Download -## Where to download prebuilt images? - -https://www.armbian.com/download/ + Armbian [releases](https://docs.armbian.com/Release_Changelog/) quarterly at the end of [February, May, August, November](https://github.com/armbian/documentation/blob/master/docs/Process_Release-Model.md). You are welcome to propose changes to our default [images build list](https://github.com/armbian/build/blob/master/config/targets.conf). - - -

⇧

- -## Additional information - -- [Build parameters and advanced build options](https://docs.armbian.com/Developer-Guide_Build-Options/), -- [Make use of user defined configurations](https://docs.armbian.com/Developer-Guide_User-Configurations/), -- [Docker](https://docs.armbian.com/Developer-Guide_Building-with-Docker/) and [Vagrant](https://docs.armbian.com/Developer-Guide_Using-Vagrant/) building guides, -- Engage in [Armbian build framework forums](https://forum.armbian.com/forum/4-development/), -- Check [Jira project management application](https://armbian.atlassian.net/browse/AR) status, -- Make use of [central project search engine](https://www.armbian.com/search), -- Browse [IRC channel logs](http://irc.armbian.com) or interact at #armbian on [Libera](https://libera.chat/). - -

⇧

- -## Build framework overview +## Project structure ```text ├── cache Work / cache directory @@ -179,61 +156,55 @@ Armbian [releases](https://docs.armbian.com/Release_Changelog/) quarterly at the    └── u-boot User: universal boot loader patches ``` -

⇧

+## 🙌 Contribution + +- You don't need to be a programmer to help! [Check out our list](https://forum.armbian.com/staffapplications/) choose what you wanna do ❤️ + +- The easiest way to help is by "Starring" our repository - it helps more people find our code. + +- You also can maintain and develop [docs](https://github.com/armbian/documentation), [CI](https://github.com/armbian/ci-testing-tools), [autotests](https://github.com/armbian/autotests), [seed torrents](https://forum.armbian.com/topic/4198-seed-our-torrents/), help on [forum moderating](https://forum.armbian.com/topic/12631-help-on-forum-moderating/), [project administration](https://forum.armbian.com/forum/39-armbian-project-administration/), [costs](https://www.armbian.com/donate). + +Please make sure to read the [Contributing Guide](.github/CONTRIBUTING.md) before you write any code. ## Support -- Have you found a bug in the **build framework**? - - Try to recreate it with a clean build framework clone. Then search for [existing and closed issues](https://github.com/armbian/build/issues). If you don't find it there, [open a new issue](https://github.com/armbian/build/issues/new). - -- Do you have troubles **elsewhere**? +- Community support Armbian is free software and provides **best effort help** through [community forums](https://forum.armbian.com/). If you can't find answer there and/or with help of [general project search engine](https://www.armbian.com/search) and [documentation](https://docs.armbian.com), consider [hiring an expert](https://www.debian.org/consultants/). -- Personalised support? +- Personal support - It is limited to active project supporters and sponsors. The shortest way to become one and receive our attention is a four figure [donation to our non-profit project](https://www.armbian.com/donate). + Personal support limited to active project supporters and sponsors. The shortest way to become one and receive our attention is a four figure [donation to our non-profit project](https://www.armbian.com/donate). -

⇧

+## Contact -## Contribute +- [Forums](https://forum.armbian.com) for Participate in Armbian +- IRC: `#armbian` on Libera.chat +- Follow [@armbian](https://twitter.com/armbian) on twitter or [LinkedIn](https://www.linkedin.com/company/armbian). +- Bugs: [issues](https://github.com/armbian/build/issues) / [JIRA](https://armbian.atlassian.net/jira/dashboards/10000) -- Adding a new feature? +## Contributors - You are welcome to suggest or contribute directly to the code with a pull request. In case your proposed changes are large, remember to discuss them prior to development. +Thank you to all the people who already contributed armbian! -- Join development? + + + - Join regulars on their active missions, start maintaining any part of the code: patches, drivers or scripted applications like [armbian-config](https://github.com/armbian/config), address [community wishes](https://github.com/armbian/build/issues), +### Also -- Help elsewhere? - - Maintain and develop [documentation](https://github.com/armbian/documentation), [CI](https://github.com/armbian/ci-testing-tools), [autotests](https://github.com/armbian/autotests), [seed torrents](https://forum.armbian.com/topic/4198-seed-our-torrents/), help on [forum moderating](https://forum.armbian.com/topic/12631-help-on-forum-moderating/), [project administration](https://forum.armbian.com/forum/39-armbian-project-administration/), [costs](https://www.armbian.com/donate). - -

⇧

- -## Social - -- [Participate in Armbian forums](https://forum.armbian.com), -- Chat with fellow users on IRC #armbian on Libera.chat, -- Follow [@armbian on Twitter](https://twitter.com/armbian) or [LinkedIN](https://www.linkedin.com/company/armbian). - -

⇧

- -## Credits - -- [Current and past contributors](https://github.com/armbian/build/graphs/contributors), our families and friends, -- [Support staff that keeps forums usable](https://forum.armbian.com/members/2-moderators/), -- [Individuals that help with their ideas](https://forum.armbian.com/), reports and [donations](https://www.armbian.com/donate). - -

⇧

+- [Current and past contributors](https://github.com/armbian/build/graphs/contributors), our families and friends. +- [Support staff](https://forum.armbian.com/members/2-moderators/) that keeps forums usable. +- [Individuals](https://forum.armbian.com/) that help with their ideas, reports and [donations](https://www.armbian.com/donate). ## Sponsors -Most of the project is sponsored with a work done by volunteer collaborators, while some part of the project costs are being covered by the industry. We would not be able to get this far without their help. +Most of the project is sponsored with a work done by volunteer collaborators, while some part of the project costs are being covered by the industry. We would not be able to get this far without their help. -[Do you want to see yourself below?](https://www.armbian.com/#contact) +[Would you like your name to appear below?](https://www.armbian.com/#contact) -

⇧

+ +## License + +This software is published under the GPL-2.0 License license.