From cb47ea8d3b6a6df2207cfb4719e024122ac8b3cf Mon Sep 17 00:00:00 2001 From: Leonid Pliushch Date: Fri, 19 Jun 2020 18:06:28 +0300 Subject: [PATCH] Update CONTRIBUTING.md --- CONTRIBUTING.md | 131 ++++++++++++++++++++++++++++++------------------ 1 file changed, 83 insertions(+), 48 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e4975c970c..5715bdb4b2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,8 @@ # Contributing -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. +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) @@ -12,35 +13,56 @@ Developer's wiki is available in https://github.com/termux/termux-packages/wiki. ## Fixing issues -By fixing bugs you will ensure that Termux packages are running smoothly. 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). Note that -solution for these issues may not be easy. +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). + +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) +and you are ready to deal with errors on your own. + +Pull requests containing incomplete work are not being merged. ### A note about package requests -We tend not to package everything what was requested, but making exception for packages that we consider important. If you -want to submit a package, make sure that following conditions are met: -- Package should have widely recognised OSS licenses like GNU GPL, MIT, Apache-2.0 and similar. -- Package should NOT be an outdated, dead project. -- Package should NOT be a part of language-specific ecosystem. Such packages are installable through `pip`, `gem`, `cpan`, `npm`. +We are rejecting package requests for single-file scripts and low-quality, infamous +and outdated, dead projects. We may also reject in packaging non-original, forked +projects. -We will reject requests for packaging single-file scripts. Also we may not package infamous projects as we need to be sure -that package is used by other people, not just by someone who requested it. +Additionally we require that requested packages met these conditions: + +- Package should have widely recognised OSS licenses like GNU GPL, MIT, Apache-2.0 + and similar. +- Package should NOT be an outdated, dead project. +- Package should NOT be a part of language-specific ecosystem. Such packages are + installable through `pip`, `gem`, `cpan`, `npm`. + +Please be ready that your package request will not be processed immediately. ## Hosting a mirror -Our APT repositories are receiving large amount of downloads per day. You can create own public mirror to help to deal with -large amount of traffic. +Consider hosting own Termux repository mirror to help to distribute bandwidth usage +between different servers. That will reduce chance of hitting the traffic quota on +our [Bintray](https://bintray.com) account. -Requirements for a server where mirror will be hosted: -- At least 20 GB of free space on HDD. -- Unlimited traffic, otherwise 3 TB monthly bandwidth + caching CDN. -- Cron job for updating mirror at least once in 24 hours. +When your mirror is ready, open the issue so we can include it into our mirror +list. -Software: you can use any utility (for example `apt-mirror`) for mirroring APT repositories as soon as it doesn't change -the file structure. Hash sums and signatures must be original, otherwise GPG verification will not be passed. +### Server requirements -Origin URLs for mirroring: +Since Bintray does not provide Rsync access to package repositories, you will need +to mirror it over HTTP. We recommend to use `apt-mirror` for that. + +Here are the server requirements: + +- 20 GB of disk free space. +- Stable network with 3+ TB of monthly bandwidth. +- Cron job for updating mirror at least once in 3 days. + +It also preferrable that your server uses a caching CDN. + +Here are the URLs for mirroring: ``` https://dl.bintray.com/termux/termux-packages-24 https://dl.bintray.com/grimler/game-packages-24 @@ -50,35 +72,40 @@ https://dl.bintray.com/xeffyr/unstable-packages https://dl.bintray.com/xeffyr/x11-packages ``` -Once your mirror is ready, open the issue so it will be added to the [list](https://github.com/termux/termux-packages/wiki/Mirrors). +If you want to include your mirror into our mirror list, ensure that monthly server's +uptime is 80% or higher. ## Updating packages -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. +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. -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. +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. ### How to update package [![asciicast](https://asciinema.org/a/gVwMqf1bGbqrXmuILvxozy3IG.svg)](https://asciinema.org/a/gVwMqf1bGbqrXmuILvxozy3IG?autoplay=1&speed=2.0) -Most packages can be updated by just modifying variables `TERMUX_PKG_VERSION` and `TERMUX_PKG_SHA256`. +Most packages can be updated by just modifying variables `TERMUX_PKG_VERSION` and +`TERMUX_PKG_SHA256`. -`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`. +- `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`. More about `build.sh` variables you can read in [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 -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. +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. -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`. +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`. ``` TERMUX_PKG_VERSION=1.0 @@ -87,11 +114,13 @@ TERMUX_PKG_REVISION=4 #### 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*. +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: +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} ``` @@ -103,26 +132,32 @@ 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. +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 -Major changes introduced to packages often make current patches incompatible with newer package version. Unfortunately, there no -universal guide about fixing patch issues as workaround is always based on changes introduced to the new source code version. +Major changes introduced to packages often make current patches incompatible +with newer package version. Unfortunately, there no universal guide about +fixing patch issues as workaround is always based on changes introduced to +the new source code version. Here are few things you may to try: -1. If patch fixing particular known upstream issue, check the project's VCS for commits fixing the issue. There is a chance that - patch is no longer needed. +1. If patch fixing particular known upstream issue, check the project's VCS + for commits fixing the issue. There is a chance that patch is no longer + needed. -2. Inspecting the failed patch file and manually applying changes to source code. Do so only if you understand the source code - and changes introduced by patch. +2. Inspecting the failed patch file and manually applying changes to source + code. Do so only if you understand the source code and changes introduced + by patch. Regenerate patch file, e.g. with: ``` diff -uNr package-1.0 package-1.0.mod > previously-failed-patch-file.patch ``` -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. +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.