Update CONTRIBUTING.md
This commit is contained in:
Leonid Pliushch
parent
bb4899c1ac
commit
cb47ea8d3b
131
CONTRIBUTING.md
131
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
|
||||
|
||||
[](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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user