Skip to content

Latest commit

 

History

History
166 lines (107 loc) · 10.3 KB

CONTRIBUTING.md

File metadata and controls

166 lines (107 loc) · 10.3 KB
Raw

Contributing to YouTube-Downloader

First off, thanks for taking the time to contribute!

The following is a set of guidelines for contributing to this project. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Table Of Contents

I don't want to read this whole thing, I just have a question!!!

What should I know before I get started?

How Can I Contribute?

Styleguides

I don't want to read this whole thing I just have a question!!!

Note: Please don't file an issue to ask a question. We have an official Gitter chat, where the community can help you if you have questions.

What should I know before I get started?

Goals

We have some goals we want to achieve with this project:

  • Create a library that delivers data and download links for youtube videos.
  • Create a UI for downloading the videos.
  • Have no external dependencies to other services.
  • Have no external dependencies to other libraries in production.
  • Installation should be foolproof (unzip on server and go)

Semantic versioning

This project contains two parts:

  1. A library that delivers data and download links for youtube videos.
  2. A Web interface that uses this library

The library should be installable via Composer so it can be used in other PHP project. It follows semantic versioning 2.

The web interface must be accessible using the index.php in the root folder. All other links and files could be changed.

How Can I Contribute?

Reporting Bugs

This section guides you through submitting a bug report. Following these guidelines helps maintainers and the community understand your report 📝, reproduce the behavior 💻 💻, and find related reports 🔎.

Before creating bug reports, please check this list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible. Fill out the required template, the information it asks for helps us resolve issues faster.

Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.

Before Submitting A Bug Report

  • Perform a search to see if the problem has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one.

How Do I Submit A (Good) Bug Report?

Bugs are tracked as GitHub issues. When creating an issue please provide the following information by filling in the template.

Every server is different and every config change has effects on the behavior of YouTube-Downloader. Explain the problem and include additional details to help maintainers reproduce the problem:

  • Use a clear and descriptive title for the issue to identify the problem.
  • Describe the exact steps which reproduce the problem in as many details as possible. For example, start by explaining how you are using YouTube-Downloader (web or library). When listing steps, don't just say what you did, but explain how you did it. For example, what url have you entered and how do you click on a link to download a viedeo.
  • Provide specific examples to demonstrate the steps. If possible include a link to your live installation so we can take a look or try it ourself.
  • If you're providing code snippets in the issue, use Markdown code blocks.
  • Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
  • Explain which behavior you expected to see instead and why.
  • Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.

Include details about your configuration and environment:

  • Which version of YouTube-Downloader are you running? You can get this information from the footer in the web interface.
  • What's the version of PHP you're using?
  • Have you modified the configuration in config/custom.php? If so, provide the contents of this file, preferably in a code block or with a link to a gist.

Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for YouTube-Downloader, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion 📝 and find related suggestions 🔎.

Before creating enhancement suggestions, please check this list as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please include as many details as possible. Fill in the template, including the steps that you imagine you would take if the feature you're requesting existed.

Before Submitting An Enhancement Suggestion

  • Perform a search to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.

How Do I Submit A (Good) Enhancement Suggestion?

Enhancement suggestions are tracked as GitHub issues, so please create an issue and provide the following information:

  • Use a clear and descriptive title for the issue to identify the suggestion.
  • Provide a step-by-step description of the suggested enhancement in as many details as possible.
  • Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples, as Markdown code blocks.
  • Describe the current behavior and explain which behavior you expected to see instead and why.
  • Include screenshots and animated GIFs which help you demonstrate the steps or point out the part of YouTube-Downloader which the suggestion is related to. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.
  • Explain why this enhancement would be useful to most YouTube-Downloader users.
  • List some other projects, libraries or applications where this enhancement exists.
  • Which version of YouTube-Downloader are you running? You can get this information from the footer in the web interface.
  • What's the version of PHP you're using?

Your First Code Contribution

Unsure where to begin contributing to YouTube-Downloader? You can start by looking through the open enhancement issues.

Please note that you contributing to an open source project. By contributing to this project:

  • you put your code under the GPL2 license
  • you assure that you have the permission to put your code under the GPL2 license

Local development

YouTube-Downloader can be developed locally, by checking out the repository and run the PHP built-in server. The requirements are:

$ git clone url-to-your-git-repository
$ cd path-to-project/
$ composer update
$ vendor/bin/phpunit
$ php -S localhost:8080

By running composer update all dependencies for development are installed by composer. Note that you also can download the composer.phar to the project folder and run $ php composer.phar update.

By running vendor/bin/phpunit all tests are being performed. You should run the tests at least once before submitting a pull request.

By running php -S localhost:8080 PHP starts the built-in server and you can use YouTube-Downloader on your machine while call http://localhost:8080 in your browser.

Pull Requests

  • Fill in the required template
  • Do not include issue numbers in the PR title
  • Include screenshots and animated GIFs in your pull request whenever possible.
  • Follow the PHP and HTML/CSS styleguides.
  • Include unit tests in the ./tests folder. Run them using vendor/bin/phpunit.
  • End all files with a newline
  • Avoid platform-dependent code
  • Place UI changes in the following folder:
    • HTML should be only in ./templates/
    • CSS should be only in ./css
  • PHP classes must follow PSR-4 autoloading and must be in the namespace YoutubeDownloader.

Styleguides

PHP Styleguide

All PHP files muss adhere to PSR-2.

We also have a .php_cs.dist file for the PHP-CS-Fixer so you can simply run the following command to fit the PHP Styleguide.

php php-cs-fixer.phar fix

HTML/CSS Styleguide

  • Code MUST use tabs for indenting, not 4 spaces.