Skip to content

Latest commit

 

History

History
187 lines (134 loc) · 10.4 KB

CONTRIBUTING.md

File metadata and controls

187 lines (134 loc) · 10.4 KB
Raw

Contribution Guidelines

Русская версия

First off, thanks for taking the time to contribute!

Your contributions increase your Rating in our community.

Please read through our Architecture Overview and Installation Instructions.

Getting Started

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the core team before making a change.

  • Make sure you have a GitHub account.
  • Submit a GitHub issue for your issue if one does not already exist.
    • A issue is not necessary for trivial changes.
  • Fork the repository on GitHub.
  • When working on an issue, create a new branch from master named for issue number or custom name. Name the branch issue/<issue-number> or issue/<custom-name>. For example issue/22 for fixing issue #22.
  • Make your changes.
  • Create a pull request to the repository.

Tips and tricks for using the Git

Key branches

  • master is the latest, deployed version.

Contribute to the core code or bug fixes

Your First Code Contribution

Start by looking through these issues:

  • Beginner issues - issues which should only require a few lines of code, and a test or two. Issues are sorted by total number of comments. While not perfect, number of comments is a reasonable proxy for impact a given change will have.
  • TODO issues - find comments with keyword TODO in the source code, with a description of a issue, and suggestions to resolve it.

Contribute/translate to documentations or messages

You can help improve documentations/translations by making them more coherent, consistent, or readable, adding missing information, correcting factual errors, fixing typos.

To help our CI servers add [ci skip] to your documentation commit message to skip build on that commit. Please remember to use it for commits containing only documentation changes.

Please read how Internationalization (I18N) works and how to find not translated texts in translation source files.

Style Guides

Git Commit Messages

  • Include an issue number to the beginning of the first line (if applicable). Example #234 YOUR_COMMIT_NAME.
  • Use the present tense ("Add feature" not "Added feature").
  • Use the imperative mood ("Move cursor to..." not "Moves cursor to...").
  • In case changing only texts or documentations include [ci skip] to the end of the first line.
  • Limit the first line to 72 characters or less.
  • Reference issues and pull requests liberally after the first line.

Documentation Style Guide

All *.md files must adhere to Markdown Syntax.

PHP Style Guide

PHP Code MUST adhere to Yii 2 Web Framework Coding Standard Style, PHP Standards Recommendations, Clean Code PHP.

Recommended IDE:

  • Atom
    • Atom-Beautify
      • PHP-CS-Fixer. The beautifier uses .php_cs file.
        • Go to "File > Settings > Packages > atom-beautify > Settings > PHP". To automatically beautify PHP code on file save toggle Beautify On Save option and select PHP-CS-Fixer as Default Beautifier.
        • Go to "File > Settings > Packages > atom-beautify > Settings > Executable > PHP-CS-Fixer". Add Binary/Script Path like ABSOLUTE_PATH_TO_PROJECT_DIR/vendor/bin/php-cs-fixer.
    • EditorConfig
    • PHP Linter
    • Yii Framework 2
  • VS Code
  • PhpStorm
    • PHP-CS-Fixer
    • SonarLint. To automatically check a code style and formatting, enable the settings in the commit window Before commit > Perform SonarLint analysis.
    • Yii 2 code styles for PhpStorm. Download the file and import to "Settings > Editor > Code Style > PHP > Import Scheme > Intellij IDEA code style XLM".
  • Eclipse
  • Sublime Text

Yii 2 migration files

https://www.yiiframework.com/doc/api/2.0/yii-db-migration

Before to create a migration files use wwwsqldesigner to prototype your changes for the database. For example you can use https://ondras.zarovi.cz/sql/demo/?keyword=default with any keyword and share the link with other contributors.

safeUp()

https://www.yiiframework.com/doc/api/2.0/yii-db-migration#safeUp()-detail

  • Name database tables in the singular to list any objects. For example, user, but not users.
  • Do not use variables like $tableName and $tableOptions.
  • Do not use database comments.
  • Add primary key to each new table. Why it so important?

Columns:

  • Primary key with integer - use $this->primaryKey()->unsigned().
  • Integer values between 0-255 - use $this->tinyInteger()->unsigned().
  • Integer values between 0-65535 - use $this->smallInteger()->unsigned().
  • Integer values above 65535 - use $this->integer()->unsigned().
  • Datetime or timeshtamp values - use $this->integer()->unsigned().
  • Do not specify a length for columns with integer values.
  • Floating-point values where precision is needed, such as money or coordinates - use $this->decimal($precision, $scale)->unsigned(). Avoid using float columns without explicit necessity, as this type is not exact.
safeDown()

https://www.yiiframework.com/doc/api/2.0/yii-db-migration#safeDown()-detail

Use only for deletion of objects of the database structure (tables, fields, keys, indexes). After creating a new migration, check if it can be rolled back and applied again.

Upgrade data in the database

To upgrade data in the database, create a migration whose name starts with upgrade_. Use data access only through DAO (yii\db\Command), not through the models. These migrations are required for existing databases.

JavaScript Style Guide

JavaScript Code MUST adhere to JavaScript Standard Style.

Recommended IDE:

  // Use this:
  export default class ClassName {

  }

  // Instead of:
  class ClassName {

  }
  export default ClassName

Composer

https://getcomposer.org/doc/04-schema.md

In all cases when composer.json file is updated, add composer.json and composer.lock files to the same commit.

Each package must contain specific version. Don't use * and @dev versions.

Programming principles and recommendations