This document describes how you, as a contributor, can help with adding packages, correcting bugs and adding features to evolution-packages.
## Package Requirements
To be included in the evolution repository, software must meet at least one of the following requirements.
Exceptions to the list are possible, and might be accepted, but are extremely unlikely.
If you believe you have an exception, start a PR and make an argument for why that particular piece of software,
while not meeting any of the following requirements, is a good candidate for the evolution packages system.
1.**System**: The software should be installed system-wide, not per-user.
1.**Compiled**: The software needs to be compiled before being used, even if it is software that is not needed by the whole system.
1.**Required**: Another package either within the repository or pending inclusion requires the package.
In particular, new themes are highly unlikely to be accepted.
Simple shell scripts are unlikely to be accepted unless they provide considerable value to a broad user base.
New fonts may be accepted if they provide value beyond aesthetics (e.g. they contain glyphs for a script missing in already packaged fonts).
Packages related to cryptocurrencies (wallets, miners, nodes, etc) are not accepted.
Browser forks, including those based on Chromium and Firefox, are generally not accepted.
Such forks require heavy patching, maintenance and hours of build time.
Software need to be used in version announced by authors as ready to use by the general public - usually called releases.
Betas, arbitrary VCS revisions, templates using tip of development branch taken at build time and releases created by the package maintainer won't be accepted.
## Creating, updating, and modifying packages in evolution by yourself
For this guide, we assume you have basic knowledge about [git](http://git-scm.org), as well as a [Centrifuge Account](http://centrifuge.hectabit.org) with SSH set up.
Using the Forgejo web editor for making changes is strongly discouraged, because you will need to clone the repo anyways to edit and test your changes.
Using the `master` branch of your fork for contributing is also strongly discouraged.
It can cause many issues with updating your pull request (also called a PR), and having multiple PRs open at once.
To create a new branch:
$ git checkout master -b <a-descriptive-name>
### Creating a new template
You can use the helper tool `xnew`, from the [xtools](https://github.com/leahneukirchen/xtools) package, to create new templates:
$ xnew pkgname subpkg1 subpkg2 ...
Templates must have the name `evolution-packages/srcpkgs/<pkgname>/template`, where `pkgname` is the same as the `pkgname` variable in the template.
For deeper insights on the contents of template files, please read the [manual](./Manual.md), and be sure to browse the existing template files in the `srcpkgs` directory of this repository for concrete examples.
### Updating a template
At minimum, a template update will consist of changing `version` and `checksum`, if there was an upstream version change, and/or `revision`, if a template-specific change (e.g. patch, correction, etc.) is needed.
Other changes to the template may be needed depending on what changes the upstream has made.
The checksum can be updated automatically with the `xgensum` helper from the [xtools](https://github.com/leahneukirchen/xtools) package:
$ xgensum -i <pkgname>
### Committing your changes
After making your changes, please check that the package builds successfully. From the top level directory of your local copy of the `evolution-packages` repository, run:
$ ./xbps-src pkg <pkgname>
Your package must build successfully for at least x86, but we recommend also trying a cross-build for armv6l* as well, e.g.:
$ ./xbps-src -a armv6l pkg <pkgname>
When building for `x86_64*` or `i686`, building with the `-Q` flag or with `XBPS_CHECK_PKGS=yes` set in `etc/conf` (to run the check phase) is strongly encouraged.
Also, new packages and updates will not be accepted unless they have been runtime tested by installing and running the package.
When you've finished working on the template file, please check it with `xlint` helper from the [xtools](https://github.com/leahneukirchen/xtools) package:
$ xlint template
If `xlint` reports any issues, resolve them before committing.
Once you have made and verified your changes to the package template and/or other files, make one commit per package (including all changes to its sub-packages). Each commit message should have one of the following formats:
`xbump`, available in the [xtools](https://github.com/leahneukirchen/xtools) package, can be used to commit a new or updated package:
$ xbump <pkgname><gitcommitoptions>
`xrevbump`, also available in the [xtools](https://github.com/leahneukirchen/xtools) package, can be used to commit a template modification for a package:
$ xrevbump '<message>' <pkgnames...>
`xbump` and `xrevbump` will use `git commit` to commit the changes with the appropriate commit message. For more fine-grained control over the commit, specific options can be passed to `git commit` by adding them after the package name.
Most pull requests should only contain a single package and dependencies which are not part of evolution-packages yet.
If you make updates to packages containing a soname bump, you also need to update `common/shlibs` and revbump all packages that are dependant.
There should be a commit for each package revbump, and those commits should be part of the same pull request.
When you make changes to your pull request, please *do not close and reopen your pull request*. Instead, just [forcibly git push](#review), overwriting any old commits. Closing and opening your pull requests repeatedly spams the evolution maintainers.
#### Continuous Integration
Pull requests are automatically submitted for Continuous Integration (CI) testing to ensure packages build and pass their tests (on native builds) on various combinations of C library and architecture.
Packages that take longer than 120 minutes or need more than 14G of storage to complete their build (for example, Firefox or the Linux kernel) will fail CI and should include `[ci skip]` in the PR title or body (the comment field when the PR is being opened) to stray from wasting CI builder time.
Use your best judgment on build times based on your local building experience. If you skip CI when submitting a PR, please build and cross-build for a variety of architectures locally, with both glibc and musl, and note your local results in PR comments.
Make sure to cover 64-bit and 32-bit architectures.
If you notice a failure in CI that didn't happen locally, that is likely because you didn't run tests locally.
Use `./xbps-src -Q pkg <package>` to do so.
Some tests won't work in the CI environment or at all, and their templates should encode this information using the `make_check` variable.
Continuous Integration will also check if the templates you have changed
comply with the our guidelines. At the moment not all packages comply with the rules, so if you update a package, it may report errors about places you haven't touched. Please feel free to fix those errors too.
#### Review
It's possible (and common) that a pull request will contain mistakes or reviewers will ask for additional tweaks.
Reviewers will comment on your pull request and point out which changes are needed before the pull request can be merged.
Most PRs will have a single commit, as seen [above](#committing-your-changes), so if you need to make changes to the commit and already have a pull request open, you can use the following commands:
$ git add <file>
$ git commit --amend
$ git push -f
A more powerful way of modifying commits than using `git commit --amend` is with [git-rebase](https://git-scm.com/docs/git-rebase#_interactive_mode), which allows you to join, reorder, change description of past commits and more.
Alternatively, if there are issues with your git history, you can make another branch and push it to the existing PR:
$ git checkout master -b <attempt2>
$ # do changes anew
$ git push -f <fork><attempt2>:<branch-of-pr>
#### Closing the pull request
Once you have applied all requested changes, the reviewers will merge your request.
If the pull request becomes inactive for some days, the reviewers may or may not warn you when they are about to close it.
Please abstain from temporarily closing a pull request while revising the templates. Instead, leave a comment on the PR describing what still needs work, add "[WIP]" to the PR title. Only close your pull request if you're sure you don't want your changes to be included.
While it is the responsibility of the PR creator to test changes before sending it, one person can't test all configuration options, usecases, hardware, etc.
Testing new package submissions and updates is always helpful, and is a great way to get started with contributing.
Then [build and install](https://centrifuge.hectabit.org/EvolutionOS/evolution-packages/src/branch/master/README.md#user-content-building-packages) the package and test its functionality.
