Skip to content

Latest commit

 

History

History
81 lines (50 loc) · 4.65 KB

CONTRIBUTING.md

File metadata and controls

81 lines (50 loc) · 4.65 KB
Raw

Contributor's Guide

First of all, thank you for contributing to Mariner!

This document provides guidelines for contributing to the project. They are written to ensure its consistency and maintainability. All contributions are welcome, as long as you follow these guidelines. If you have any questions, please contact me.

There are many ways to contribute to the project, including, but not limited to, submitting bug reports and feature requests, improving documentation or writing code.

How to Report Bugs

Bug reports are hugely important, but please make sure to avoid duplicate reports. Before you submit one, please check Mariner issues, both open and closed, and make sure, that the bug has not been reported before.

When filing an issue, include answers to the following five questions:

  1. What version of Mariner are you using?
  2. What operating system and Python version are you using?
  3. What did you do?
  4. What was the expected result?
  5. What was the actual result?

In addition, consider providing logs (by default in ~/.local/share/mariner/mariner.log).

How to Suggest a Feature

If you have a suggestion for a feature or an enhancement, please feel free to open an issue. In your feature request, include the following:

  1. What should the feature do?
  2. Why do you need it?
  3. How should it work?

Note that I reserve a right to reject a feature request, if I feel it does not align with the project's goals.

Contributing Code

If this is your first time contributing code on Gitlab, take a look at Gitlab's How to create a merge request. After you read it, you follow this checklist to make a merge request:

  1. Fork the repository.
  2. Setup development environment using poetry install && pre-commit install
  3. Run the tests using pytest tests to make sure they pass on your system.
  4. Write tests for the feature you are adding. They should fail.
  5. Add your feature.
  6. Run the test suite again, ensuring all tests, including the ones you have written, pass.
  7. Make a merge request on Gitlab.

Code Style

  • Mariner adheres to Pep 8 and Pep 257 coding conventions with line length up to one 100 characters.
  • It also takes advantage of type hints. For an explanation of how they work, read Pep 483
  • Use Google style docstrings.
  • Use imports for packages and modules only.
  • Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert.

Add Support For a Torrent Tracker

Adding support for another tracker is quite straightforward. First of all, you need to make a new module in the plugins directory. Them module should contain a class named after the torrent tracker, which inherits from the TrackerPlugin class. The plugin will be automatically loaded under the name of the class.

The TrackerPlugin base class takes care of most things, such as fetching the results page etc. Under most circumstances, the only things needed, are setting the search_url class attribute and defining _parse method.

search_url is the URL of the result page for search string. You can get it by running a search on your chosen tracker and deleting the search string from the URL. {title} is the searched string.

The _parse method is the hard part. You have to parse the results page for relevant information, such as torrent name, torrent URL, magnet link etc. and return it as a list of Torrent objects from the torrent module. Mariner uses BeautifulSoup library for parsing HTML. You can find more information on its usage in the documentation documentation.

Optionally, you can provide aliases class attribute. aliases is a list of alternative names, which can users use to refer to the plugins. An example would be the PirateBay module, which has the following aliases:

aliases = ['tpb', 'pb']

As a result, users can refer to it as piratebay, tpb or pb.

Updating Documentation

If you have found any mistakes, want to add examples, or just improve the documentation in general, you are more than welcome! Just make your change and send a merge request.

Closing Words

Thank you for taking the time to read the Contributor's Guide!

Radek Sprta

Maintainer