CONTRIBUTING.md

Contributing

First off, thank you for considering contributing to Telegram Media Downloader. It's people like you that make telegram-media-downloader such a great tool. Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved.

Where do I go from here?

If you've noticed a bug or have a feature request, make one! It's generally best if you get confirmation of your bug or approval for your feature request this way before starting to code.

If you have a general question about telegram-media-downloader, you can ask it on Discussion under Q&A category and any ideas/suggestions goes under Ideas category, the issue tracker is only for bugs and feature requests.

Fork & create a branch

If this is something you think you can fix, then fork telegram-media-downloader and create a branch with a descriptive name.

A good branch name would be (where issue #52 is the ticket you're working on):

	git checkout -b 52-fix-expired-file-reference

For new Contributors

If you never created a pull request before, welcome Here is a great tutorial on how to send one :)

1. Fork the project, clone your fork, and configure the remotes:

   # Clone your fork of the repo into the current directory
   git clone https://github.com/<your-username>/<repo-name>
   # Navigate to the newly cloned directory
   cd <repo-name>
   # Install dependencies
   make dev_install
   # Assign the original repo to a remote called "upstream"
   git remote add upstream https://github.com/Dineshkkarthik/<repo-name>

2. If you cloned a while ago, get the latest changes from upstream:

   git checkout master
   git pull upstream master

3. Create a new branch (off the main project master branch) to contain your feature, change, or fix based on the branch name convention described above:

   git checkout -b <branch-name>

4. Make sure to update, or add to the tests when appropriate. Patches and features will not be accepted without tests. Run make test to check that all tests pass after you've made changes.

5. If you added or changed a feature, make sure to document it accordingly in the README.md file.

6. Push your branch up to your fork:

   git push origin <branch-name>

7. Open a Pull Request with a clear title and description.

Coding Standards

Python style

Please follow these coding standards when writing code for inclusion in telegram-media-downloader.

Telegram-media-downloader follows the PEP8 standard and uses Black and Pylint to ensure a consistent code format throughout the project.

Continuous Integration using GitHub Actions will run those tools and report any stylistic errors in your code. Therefore, it is helpful before submitting code to run the check yourself:

black media_downloader.py utils

to auto-format your code. Additionally, many editors have plugins that will apply black as you edit files.

Writing good code is not just about what you write. It is also about how you write it. During Continuous Integration testing, several tools will be run to check your code for stylistic errors. Generating any warnings will cause the test to fail. Thus, good style is a requirement for submitting code to telegram-media-downloader.

This is already added in the repo to help contributors verify their changes before contributing them to the project:

make style_check

Type hints

Telegram-media-downloader strongly encourages the use of PEP 484 style type hints. New development should contain type hints and pull requests to annotate existing code are accepted as well!

Types imports should follow the from typing import ... convention. So rather than

import typing

primes: typing.List[int] = []

You should write

from typing import List, Optional, Union

primes: List[int] = []

Optional should be used where applicable, so instead of

maybe_primes: List[Union[int, None]] = []

You should write

maybe_primes: List[Optional[int]] = []

Validating type hints

telegram-media-downloader uses mypy to statically analyze the code base and type hints. After making any change you can ensure your type hints are correct by running

make static_type_check

Docstrings and standards

A Python docstring is a string used to document a Python module, class, function or method, so programmers can understand what it does without having to read the details of the implementation.

The next example gives an idea of what a docstring looks like:

def add(num1: int, num2: int) -> int:
   """
   Add up two integer numbers.

   This function simply wraps the ``+`` operator, and does not
   do anything interesting, except for illustrating what
   the docstring of a very simple function looks like.

   Parameters
   ----------
   num1: int
      First number to add.
   num2: int
      Second number to add.

   Returns
   -------
   int
      The sum of ``num1`` and ``num2``.

   See Also
   --------
   subtract : Subtract one integer from another.

   Examples
   --------
   >>> add(2, 2)
   4
   >>> add(25, 0)
   25
   >>> add(10, -10)
   0
   """
   return num1 + num2

Some standards regarding docstrings exist, which make them easier to read, and allow them be easily exported to other formats such as html or pdf.

Commit Message

telegram-media-downloader uses a convention for commit message prefixes and layout. Here are some common prefixes along with general guidelines for when to use them:

<prefix>: <subject>
<-- OPTIONAL -->
<BLANK LINE>
<body>

Prefix:

Must be one of the following:

• add: Adding a new file
• ci: Changes to CI configuration files and scripts (example: files inside .github folder)
• clean: Code cleanup
• docs: Additions/updates to documentation
• enh: Enhancement, new functionality
• fix: Bug fix
• perf: A code change that improves performance
• refactor: A code change that neither fixes a bug nor adds a feature
• style: Changes that do not affect the meaning of the code (white-space, formatting, etc)
• test: Additions/updates to tests
• type: Type annotations

Subject:

Please reference the relevant GitHub issues in your commit message using #1234.

• a subject line with < 80 chars.
• summary in present tense.
• not capitalized.
• no period at the end.

Commit Message Body

Just as in the summary, use the imperative, present tense.

Explain the motivation for the change in the commit message body. This commit message should explain why you are making the change. You can include a comparison of the previous behavior with the new behavior in order to illustrate the impact of the change.

Code of Conduct

As a contributor, you can help us keep the community open and inclusive. Please read and follow our Code of Conduct.