sergiotarxz/termux-packages
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

update CONTRIBUTING.md

Browse Source
This commit is contained in:
Leonid Pliushch 2021-07-31 18:36:43 +03:00
parent 191c273818
commit 1a60935480
No known key found for this signature in database
GPG Key ID: 45F2964132545795
2 changed files with 223 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/ISSUE_TEMPLATE/package_request.md vendored
View File

@ -5,9 +5,7 @@ about: Suggest a new package.
## Requesting 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 packaging policy](https://github.com/termux/termux-packages/blob/master/CONTRIBUTING.md#packaging-policy).
- [ ] I have read [Termux policy on package requests](https://github.com/termux/termux-packages/blob/master/CONTRIBUTING.md#a-note-about-package-requests).
*** ***

313
CONTRIBUTING.md
View File

@ -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 However, most of work is done by Termux maintainers on their spare time and
therefore only priority tasks are being completed. 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. 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 - **Reporting issues**
[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, If you have found issue, let the community know about it.
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.
Contributors should take full responsibility about submitted changes. Pull requests Please be prepared that issue may not be resolved immediately. We will ignore
containing incomplete work or disruptive changes will NOT be merged. 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 Bugs reports for legacy Termux installations (Android 5.x / 6.x) are not
that Termux maintainers team is small and we prefer to use free hosting for packages accepted. We already dropped support for these Android OS versions.
repository. In order to be able to provide services at reasonable quality, we have
to put restrictions on acceptable package requests.
Here are general conditions which should be met to include the requested package in - **Examining existing packages for potential issues**
our repositories:
- Packages must be active, well-known projects. Those which are already included into There could be undiscovered bugs in packages. For example: unspecified
major Linux distributions like Debian have more chances to be included in Termux. dependencies, unprefixed hardcoded FHS paths, crashes, etc.
Outdated, dead projects are not accepted.
- Packages must be licensed under widely-recognised open source license like Apache-2.0, If you can't submit a pull request with patches fixing the problem, you can
GNU GPL, MIT and similar. Open source but non-free packages are acceptable and are open new [issue](https://github.com/termux/termux-packages/issues/new/choose).
processed on individual basis. Packages which are closed source are not accepted.
- Packages must NOT be a part of language-specific ecosystem. These packages are - **Fixing known bugs**
installable through `cpan`, `gem`, `npm`, `pip` and similar.
- 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 - **Submitting new packages**
double purpose like Nmap.
Also we will reject any requests for low-quality packages, simple utilities consisting There are lots of unresolved [package requests](https://github.com/termux/termux-packages/issues?q=is%3Aissue+is%3Aopen+label%3A%22package+request%22).
of one-file scripts and scripts which automate use of existing packages. Pay attention to tickets having tag `help wanted`.
We want to be sure that are adding useful things into our repositories. So when - **Keeping existing packages up-to-date**
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.
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 - **Hosting a package repository mirror**
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) Termux generates lots of traffic. Mirrors help to reduce load on primary
page to see what is outdated and submit a pull request with version update. 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 ## Requesting new package
`TERMUX_PKG_SHA256`.
- `TERMUX_PKG_VERSION`: a text field containing an original version of package. If you are looking for specific package and didn't find it included in our
- `TERMUX_PKG_SHA256`: a text field or an array of text fields containing SHA-256 repositories, you can request it.
checksum for each source code bundle defined by `TERMUX_PKG_SRCURL`.
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). 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 [![asciicast](https://asciinema.org/a/gVwMqf1bGbqrXmuILvxozy3IG.svg)](https://asciinema.org/a/gVwMqf1bGbqrXmuILvxozy3IG?autoplay=1&speed=2.0)
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 You can check which packages are out-of-date by visiting Termux page on
build.sh script easily readable, we require revision variable to be placed on [Repology](https://repology.org/projects/?inrepo=termux&outdated=1).
the next line after `TERMUX_PKG_VERSION`.
``` Most of packages can be updated by just modifying variables `TERMUX_PKG_VERSION`
TERMUX_PKG_VERSION=1.0 and `TERMUX_PKG_SHA256`, which represent the package version and checksum for
TERMUX_PKG_REVISION=4 source code archive respectively.
```
#### Downgrading a package or changing versioning scheme ### Dealing with patch errors
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
Major changes introduced to packages often make current patches incompatible Major changes introduced to packages often make current patches incompatible
with newer package version. Unfortunately, there no universal guide about 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, 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 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. 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`.