Contributing

Code

The place for official plugin repositories is the Albert launcher organization. Distributed native plugins are submodules in the Albert repository plugins directory. Python plugins in the Python repository plugins directory respectively.

The main branch of a plugin repository represents the latest version that is or will be distributed with the application and therefore has to be protected. Contributions have to pass peer reviewing via pull request. As such contributors have to work on their own fork and send a PR. The rationale is to ensure

  • Safety. For users and developers.
  • Simplicity. Upstream main branch is reviewed and distributable.
  • Tidiness. git status is clean or contains approved plugin changes.

Fixes and Features

Before putting a lot of effort into a contribution, open an issue and discuss your planned changes. This is important, because there is a chance that your changes may be rejected. Contributing to existing plugins is straightforward.

  1. Fork the repository to your account.
  2. Work on on the fork.
  3. Send a pull request to the upstream repository.
  4. Go through the review process until approved.

New plugins

We highly appreciate new plugin additions, however to be shipped there should be a demand for its use case. If you want your plugin to be added to the official repositories, put it to the list of candidates in the awesome-albert repository and promote it in the community chat. Plugins without users/stars will not be added to the official repositories. Once your plugin has some stars, you can request its addition to the official repositories.

For a plugin to be accepted it has to satisfy the following requirements:

  • The project is licensed under a permissive open source license (e.g. MIT, Apache, BSD).
  • The project has an active maintainer.
  • The repository content is essential to the functionality of the plugin. Keep in mind that in future somebody else may want to maintain the plugin and for distribution the size of the repository should be minimal.
  • Icons are vector graphics or 128x128 raster images.

Having a concise README.md summarizing features, requirements, limitations, supported platforms and implementation details is recommended.

Reviews

Reviews are extremely important to ensure the quality of the code and the safety of users and developers. Reviews have always been a bottleneck in the past, so we are looking for reviewers.

You could review open pull requests any time or join the reviewer teams. Three members of the reviewer team will be assigned on new pull requests of any (new) plugin. Leave a message with your GitHub username to get an invite.

If you want to help with just some particular plugins, consider becoming a maintainer instead (see below).

Maintenance

If you are using a plugin a lot and have basic programming skills you are probably a good plugin maintainer.

As passive maintainer you can help by using the plugin, reporting issues and sending pull requests containing fixes and features. As an active/official maintainer you will be assigned on new issues and pull requests. A maintainer is implicitly a reviewer of its plugin.

To opt-in send a pull request adding your GitHub username to the maintainers list of the plugin metadata. Revert to opt-out.

Documentation

Each page on the website contains an ‘Edit this page on GitHub’ link in the footer that you can use to send improvements. The API reference is generated from source code, in particular the header files of the public API. To improve the API reference, send a pull request with the changes to the header files in the include directory in the Albert repository.

Promotion

Appreciation

Support me (@manuelschneider) as a creator by becoming a sponsor or donating. Do not forget the authors and maintainers of your most beloved plugins. Check their GitHub profiles for donation links.