From 1a6093548033b975e1dca49c0f234c1f30c4946c Mon Sep 17 00:00:00 2001 From: Leonid Pliushch Date: Sat, 31 Jul 2021 18:36:43 +0300 Subject: [PATCH] update CONTRIBUTING.md --- .github/ISSUE_TEMPLATE/package_request.md | 4 +- CONTRIBUTING.md | 313 +++++++++++++++------- 2 files changed, 223 insertions(+), 94 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/package_request.md b/.github/ISSUE_TEMPLATE/package_request.md index 26a17e2f6..ca81327d8 100644 --- a/.github/ISSUE_TEMPLATE/package_request.md +++ b/.github/ISSUE_TEMPLATE/package_request.md @@ -5,9 +5,7 @@ about: Suggest a new package. ## Requesting new package -*Not every package request can be fulfilled. Our repository is big enough to imply some issues with maintaining and hosting.* - -- [ ] I have read [Termux policy on package requests](https://github.com/termux/termux-packages/blob/master/CONTRIBUTING.md#a-note-about-package-requests). +- [ ] I have read [Termux packaging policy](https://github.com/termux/termux-packages/blob/master/CONTRIBUTING.md#packaging-policy). *** diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ed5c842b5..3eec2b00d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,127 +4,205 @@ Termux is an open source application and it is built on users' contributions. However, most of work is done by Termux maintainers on their spare time and therefore only priority tasks are being completed. -Here are ways how you can help: -- [Fixing issues](#fixing-issues) -- [Hosting a mirror](#hosting-a-mirror) -- [Updating packages](#updating-packages) - Developer's wiki is available at https://github.com/termux/termux-packages/wiki. -## Fixing issues +## How you can contribute to Termux project -Contribute to Termux by submitting new packages or fixing bugs. Pay attention to -[issues](https://github.com/termux/termux-packages/issues) labeled as -["bug report"](https://github.com/termux/termux-packages/issues?q=is%3Aopen+is%3Aissue+label%3A%22bug+report%22) -and ["help wanted"](https://github.com/termux/termux-packages/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22). +- **Reporting issues** -Note that issue solving may not be easy. If you decided to contribute to @termux, -ensure that you read the [developer's wiki](https://github.com/termux/termux-packages/wiki). -You will also need some basic knowledge about Shell Scripting and build systems -like Autotools or CMake. + If you have found issue, let the community know about it. -Contributors should take full responsibility about submitted changes. Pull requests -containing incomplete work or disruptive changes will NOT be merged. + Please be prepared that issue may not be resolved immediately. We will ignore + statements like "solve it quickly", "urgently need solution" and so on. Be + patient. -### A note about package requests + You may report only issues happening within our official packages. Do not + submit issues happening in third-party software - we will ignore them. -Termux keeps more than 1000 packages in its repositories. That is quite many, considering -that Termux maintainers team is small and we prefer to use free hosting for packages -repository. In order to be able to provide services at reasonable quality, we have -to put restrictions on acceptable package requests. + Bugs reports for legacy Termux installations (Android 5.x / 6.x) are not + accepted. We already dropped support for these Android OS versions. -Here are general conditions which should be met to include the requested package in -our repositories: +- **Examining existing packages for potential issues** -- Packages must be active, well-known projects. Those which are already included into - major Linux distributions like Debian have more chances to be included in Termux. - Outdated, dead projects are not accepted. + There could be undiscovered bugs in packages. For example: unspecified + dependencies, unprefixed hardcoded FHS paths, crashes, etc. -- Packages must be licensed under widely-recognised open source license like Apache-2.0, - GNU GPL, MIT and similar. Open source but non-free packages are acceptable and are - processed on individual basis. Packages which are closed source are not accepted. + If you can't submit a pull request with patches fixing the problem, you can + open new [issue](https://github.com/termux/termux-packages/issues/new/choose). -- Packages must NOT be a part of language-specific ecosystem. These packages are - installable through `cpan`, `gem`, `npm`, `pip` and similar. +- **Fixing known bugs** -- Packages must NOT duplicate functionality of the already present ones. + Take a look at https://github.com/termux/termux-packages/issues. There many + issue tickets having tag `bug report` or `help wanted`. They all are waiting + to be resolved. -- Packages must NOT be phishing or pentesting tools. This does not apply for tools with - double purpose like Nmap. +- **Submitting new packages** -Also we will reject any requests for low-quality packages, simple utilities consisting -of one-file scripts and scripts which automate use of existing packages. + There are lots of unresolved [package requests](https://github.com/termux/termux-packages/issues?q=is%3Aissue+is%3Aopen+label%3A%22package+request%22). + Pay attention to tickets having tag `help wanted`. -We want to be sure that are adding useful things into our repositories. So when -requesting a package, please provide a brief description what package does and why -we should add it. Statements like `"it's hard to compile on device"`, `"I request it -because I need it"`, `"it's convenient to install it with package manager"` are -NOT valid reasons to request a package. +- **Keeping existing packages up-to-date** -Please be ready that your package request will not be processed immediately. + Packages do not update themselves on their own. Someone needs to update build + script and patches. Usually they are handled by maintainers but things are + often outdated. -## Updating packages + See [Updating packages](#updating-packages) for details. -Keeping packages up-to-date ensures that Termux users' will not experience the upstream -bugs or security issues and will be able to use the latest features. +- **Hosting a package repository mirror** -Periodically check the [Repology](https://repology.org/projects/?inrepo=termux&outdated=1) -page to see what is outdated and submit a pull request with version update. + Termux generates lots of traffic. Mirrors help to reduce load on primary + server, provide better download speeds and eliminate single point of failure. -### How to update package +- **Donate** -[![asciicast](https://asciinema.org/a/gVwMqf1bGbqrXmuILvxozy3IG.svg)](https://asciinema.org/a/gVwMqf1bGbqrXmuILvxozy3IG?autoplay=1&speed=2.0) + See https://github.com/termux/termux-packages/wiki/Donate for details. -Most packages can be updated by just modifying variables `TERMUX_PKG_VERSION` and -`TERMUX_PKG_SHA256`. +## Requesting new package -- `TERMUX_PKG_VERSION`: a text field containing an original version of package. -- `TERMUX_PKG_SHA256`: a text field or an array of text fields containing SHA-256 - checksum for each source code bundle defined by `TERMUX_PKG_SRCURL`. +If you are looking for specific package and didn't find it included in our +repositories, you can request it. + +Open a new [issue](https://github.com/termux/termux-packages/issues/new/choose) +filling the `package request` template. You will need to provide at least +package description and its home page and URL to source repository. Remember +that your request will not be processed immediately. + +Requested package must comply with our [packaging policy](#packaging-policy). + +## Packaging policy + +There are already more than 1000 packages added to Termux repositories. All +of them needs to be maintained, kept up-to-date. Unlike the major distributions, +our developers team is small and we also limited on server disk space. + +In order to provide service at reasonable quality, requested packages should +met these conditions: + +- **Packages must be active, well-known projects** + + Software available in major Linux distributions has more chances to be + included into Termux repositories. We will not accept outdated, dead projects + as well as projects which do not have active community. + +- **Packages must be licensed under widely recognized open source license** + + Software should be licensed under Apache, BSD, GNU GPL, MIT or other well + known open source license. Software which is open source but is distributed + under non-free conditions is processed on individual basis. + + Software which is either closed-source, contain binary-only components or + is distributed under End User License Agreement is not accepted. + +- **Not installable through cpan, gem, npm, or pip** + + These packages should be installable through `cpan`, `gem`, `npm`, `pip` and + so on. + + Packaging modules for Perl, Ruby, Node.js, Python is problematic, especially + when it comes to cross-compiling native extensions. Also remember that disk + space on our server is *finite*, so it is better to keep room for the more + important things. + +- **Not serving duplicated functionality** + + Please avoid submitting packages which duplicate functionality of already + present ones. + + The more useless packages in repositories, the less overall packaging and + service quality - *remembering that our resources are limited?* + +- **Not serving hacking, phishing, spamming, spying, ddos functionality** + + We do not accept packages which serve solely destructive or privacy violation + purposes, including but not limited to pentesting, phishing, bruteforce, + sms/call bombing, DDoS attaks, OSINT. + +## Submitting pull requests + +Contributors take the all responsibility for their submissions. Maintainers may +provide some help with fixing your pull request or give some recommendations, +but that DOES NOT mean they will do all work instead of you. + +**Minimal requirements:** +- Experience with Linux distribution like Debian (preferred), Arch, Fedora, etc. +- Experience with compiling software from source. +- Good shell scripting skills. +- You have read https://github.com/termux/termux-packages/wiki. + +If you never used Linux distribution or Termux was your first experience with +Linux environment, we strongly recommending to NOT send pull requests since +we will reject low quality work. + +Do not forget about [packaging policy](#packaging-policy) when submitting a +new package, as your pull request will be closed without merge. + +Do not send disruptive changes, like without reason reverting commits or +deleting files, creating spam content, etc. Authors of such pull requests may +be blocked from contributing to [Termux](https://github.com/termux) project. + +*** + +# Working with packages + +All software available in Termux repositories aims to be compatible with Android +OS and is built by Android NDK. This often introduces compatibility issues as +Android (specifically Termux) is not a standard platform. Do not expect there +are exist package recipes available out-of-box. + +## Basics + +Each package is a defined through the `build.sh` script placed into directory +`./packages//` where `` is the actual name of package in lower case. +File `build.sh` is a shell (Bash) script that defines some properties like +dependencies, description, home page through environment variables. Sometimes +it also used to override default packaging steps defined in our build system. + +Here is example of `build.sh`: + +```.sh +TERMUX_PKG_HOMEPAGE=https://example.com +TERMUX_PKG_DESCRIPTION="Termux package" +TERMUX_PKG_LICENSE="GPL-3.0" +TERMUX_PKG_MAINTAINER="@github" +TERMUX_PKG_VERSION=1.0 +TERMUX_PKG_SRCURL=https://example.com/sources-${TERMUX_PKG_VERSION}.tar.gz +TERMUX_PKG_SHA256=0000000000000000000000000000000000000000000000000000000000000000 +TERMUX_PKG_DEPENDS="libiconv, ncurses" +``` + +It can contain some additional variables: +- `TERMUX_PKG_BUILD_IN_SRC=true` + + Use this variable if package supports in-tree builds only, for example if + package uses raw Makefile instead of build system like CMake. + +- `TERMUX_PKG_PLATFORM_INDEPENDENT=true` + + This variable specifies that package is platform-independent and can run + on any device regardless of CPU architecture. + +`TERMUX_PKG_LICENSE` should specify the license using SPDX license identifier +or can contain values "custom" or "non-free". Multiple licenses should be +separated by commas. + +`TERMUX_PKG_SRCURL` should contain URL only for the official source bundle. +Use of forks is allowed only under a good reason. More about `build.sh` variables you can read on [developer's wiki](https://github.com/termux/termux-packages/wiki/Creating-new-package#table-of-available-package-control-fields). -#### Rebuilding package with no version change +## Updating packages -Changes to patch files and build configuration options require submission of a new -package release with a different version string. As we can't modify the original -package version, we append a number called *revision*. This number should be -incremented on each submitted build whenever project's version remains to be same. +[![asciicast](https://asciinema.org/a/gVwMqf1bGbqrXmuILvxozy3IG.svg)](https://asciinema.org/a/gVwMqf1bGbqrXmuILvxozy3IG?autoplay=1&speed=2.0) -Revision is specified through `TERMUX_PKG_REVISION` build.sh variable. To have -build.sh script easily readable, we require revision variable to be placed on -the next line after `TERMUX_PKG_VERSION`. +You can check which packages are out-of-date by visiting Termux page on +[Repology](https://repology.org/projects/?inrepo=termux&outdated=1). -``` -TERMUX_PKG_VERSION=1.0 -TERMUX_PKG_REVISION=4 -``` +Most of packages can be updated by just modifying variables `TERMUX_PKG_VERSION` +and `TERMUX_PKG_SHA256`, which represent the package version and checksum for +source code archive respectively. -#### Downgrading a package or changing versioning scheme - -Sometimes we need to downgrade a package or in any other way to change format of -version string but we also need to tell package manager that this is a new package -version which should be installed with `apt upgrade`. To force new build to be a -package update, we set a *package epoch*. - -We don't have separate build.sh variable for specifying epoch, so we doing that -through `TERMUX_PKG_VERSION` variable. It takes following format: -``` -${EPOCH}:${ORIG_VERSION} -``` - -Epoch should be bumped on each change of versioning scheme or downgrade. - -``` -TERMUX_PKG_VERSION=1:0.5 -TERMUX_PKG_REVISION=4 -``` - -Note that if you are not @termux collaborator, pull request must contain a -*description* why you are submitting a package downgrade. All pull requests -which submit package downgrading without any serious reason will be denied. - -#### Dealing with patch errors +### Dealing with patch errors Major changes introduced to packages often make current patches incompatible with newer package version. Unfortunately, there no universal guide about @@ -149,3 +227,56 @@ Here are few things you may to try: Always check the CI (Github Actions) status for your pull request. If it fails, then either fix or close it. Maintainers can fix it on their own, if issues are minor. But they won't rewrite whole your submission. + +## Rebuilding package with no version change + +Changes to patch files and build configuration options will imply package +rebuild. In order to make package recognized as update, a build number should +be set. This is done through defining variable `TERMUX_PKG_REVISION` or +incrementing its value if already set. + +`TERMUX_PKG_REVISION` should be set exactly below `TERMUX_PKG_VERSION`: + +```.sh +TERMUX_PKG_VERSION=1.0 +TERMUX_PKG_REVISION=4 +``` + +If package version has been updated, `TERMUX_PKG_REVISION` should be removed. + +## Downgrading the package or changing versioning scheme + +If package needs to be downgraded or for versioning scheme needs to be changed, +you need to set or increment package epoch. This is needed to tell package +manager force recognize new version as package update. + +Epoch should be specified in same variable as version (`TERMUX_PKG_VERSION`), +but its value will take different format (`{EPOCH}:{VERSION}`): + +```.sh +TERMUX_PKG_VERSION=1:5.0.0 +``` + +Note that if you are not @termux collaborator, pull request must contain a +*description* why you are submitting a package downgrade. All pull requests +which submit package downgrading without any serious reason will be rejected. + +## Common build issues + +``` +No files in package. Maybe you need to run autoreconf -fi before configuring? +``` + +Means that build system cannot find the Makefile. Depending on project, there +are some tips for trying: +- Set `TERMUX_PKG_BUILD_IN_SRC=true` - applicable to Makefile-only projects. +- Run `./autogen.sh` or `autoreconf -fi` in `termux_step_pre_configure`. This + is applicable to projects that use Autotools. + +``` +No LICENSE file was installed for ... +``` + +This error happens when build system cannot find license file and it should be +specified manually through `TERMUX_PKG_LICENSE_FILE`. +