update CONTRIBUTING.md
This commit is contained in:
parent
191c273818
commit
1a60935480
4
.github/ISSUE_TEMPLATE/package_request.md
vendored
4
.github/ISSUE_TEMPLATE/package_request.md
vendored
@ -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).
|
||||
|
||||
***
|
||||
|
||||
|
313
CONTRIBUTING.md
313
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/<name>/` where `<name>` 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`.
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user