Commit Policy/ru

This article may require cleanup to meet the Qt Wiki's quality standards. Reason: Auto-imported from ExpressionEngine. Please improve this article if you can. Remove the {{cleanup}} tag and add this page to Updated pages list after it's clean.

Russian English 简体中文

Политика внесения изменений

Правила

Далее описаны главные правила для создания и публикации изменений в любые репозитории Qt. Как обычно в Qt, ни одно из этих правил не является абсолютно верным, но вы будете обьектом насмешек если нарушите их без обьективной причины.

1. . Если вы добавляете новую функцию/класс:
   1. Убедитесь в том, что все задокументировано правильно.
   2. Следуйте Api_Design_Principles. Обсудите и сверьте имена функций/классов с другими Qt разработчиками (conduct API reviews).
2. Весь код должен соответствовать Coding_Conventions.
3. Для программирования GUI, следуйте руководству по стилю (да, это от KDE), следуйте советам по переводу Qt Creator и избеайте ошибки локализации.
4. Убедитесь что ваши изменения компилируются и работают на всех платформах.
5. Проверьте что нет никакой регрессии в модульных тестах (для большей информации взляните на Qt_Autotests_Environment).
6. Пишите новые модульные тесты для багов которые вы устранили или вами добавленного нового функционала.
7. Оформляйте новый или изменённый вами код в соответствии с Qt_Coding_Style.
8. Produce commits which facilitate reviews and contribute to a useful history which can be read, searched, annotated and cherry-picked. Here are some hints:
   1. Make minimal and atomic commits. That means that each commit should contain exactly one self-contained change - don't mix unrelated changes, and don't create inconsistent states. Never "hide" unrelated fixes in bigger commits. Make coding style fixes only in exactly the lines which contain the functional changes, and comment fixes only when they relate to the change - the rest is for a separate commit.
   2. Write descriptive commit messages. Make them self-contained, so people don't have to research the historical context to make sense of them. Conversely, don't put unnecessary trivia into them. Tell why you changed something unless it is completely self-evident. Use the Qt commit template: Follow the summary + description message style and use pseudo-headers to reference JIRA issues, reviewers, etc. and consider the generic Git commit message guidelines.
   3. Commit often. Use

      git gui
      

      and

      git rebase -i
      

      extensively to get your history into shape.
   4. Avoid unnecessary merges. Use

      git pull —rebase
      

      unless you have an unpushed "proper" merge.
9. Get a review from somebody who knows the code before you publish. If there is no candidate yet, introduce somebody to the code. Note that pushing to your private clone does not count as publishing and is a perfectly valid way to solicit a review or make a backup of a work in progress.
10. Don't commit anything you don't understand. "Somehow it suddenly works" is not acceptable. Reverting when a proper fix would be possible is admitting defeat. ;)
11. Review your changes before you push.

    git log —stat
    

    ,

    git log -p
    

    and

    gitk
    

    are your friends.
12. Don't fight the git pre-receive hooks. See below.
13. And most importantly: use your brain before hitting

    <enter>
    

    .

h2. The pre-receive Hooks

Our internal git repositories have various pre-receive hooks installed which ensure some minimal quality standards and legal safety. The sanitizer script (without the privacy check) is available from the devscripts repository. The checks are:

1. The privacy check. It tries to ensure that no real names are published without explicit consent. A side effect is that it will complain about invalid committer information, which is Good ™. Valid addresses from external contributors are added to a whitelist; that process is semi-automated.
2. The line ending check. We are developing in a heterogeneous environment with both Unix and Windows machines. Therefore it is imperative to have all files in the repository in the canonical LF-only format. Windows users need to set the git option

   core.autocrlf
   

   to

   true
   

   to automatically get CRLF line endings which are suitable for the native tools.
3. Conflict marker check. Unless you are adding a text file which contains the patterns on purpose, you most probably botched a merge/rebase.
4. Generated file check. Don't commit generated files- they bloat the repository and create spurious changes. If a file is generated but you don't know how to automate the build process, ask an expert.
5. Check for project/config files of alien build systems. As we are using qmake, these will in most cases fall under the "generated file" rule anyway.
6. Big file addition check. Think three times whether you really need that huge media file, test binary or screenshot. As we are using git, such mistakes are not correctable - once you added a huge file, everyone who clones the repository will have to pay for it with network traffic and disk space for all times. Source code files are exempt from the check at all; for the rest it is a bit paranoid (it will complain about anything bigger than 50 KiB or an instantaneous file growth over 150% if the file is bigger than 20 KiB).
7. Huge file addition check. If you trigger that one, you almost certainly did something wrong.
8. Work In Progress push check. This is meant to avoid that you accidentally push something you marked for later cleanup. It checks for the strings "WIP" and "'*" in the summary line and for an empty Reviewed-by line. This check is disabled in the local post-commit hook for obvious reasons.
9. Check for mixing whitespace and non-whitespace changes. A commit may contain only whitespace changes or "proper" changes (with whitespace cleanups only on already changed lines, and, as an exception, additions and removals of empty lines). This helps to ensure the usefulness of

   git blame
   

   (note that a clean history is better than using

   git blame -w
   

   , as the latter will also hide significant whitespace changes). (currently advisory only)
10. Some simple coding style checks. (currently advisory only)

The checks can be overridden on a case by case basis when needed. Don't even think about overriding any of them unless you have a really good reason. "I need to get this done now" is not a valid reason. Neither is "I cannot be bothered to understand what it wants from me". If there is any doubt, discuss alternatives with somebody appropriate.

Each error/warning message mentions the key needed to override it. Note that there is only one key per entire category, so make sure to check all reports before you apply the override.

The recommended override command is printed by the hook itself. Don't export the environment variable in the current shell, as you will inevitably forget to unset it again and thus disarm the hooks semi-permanently.

For the overrides to work, you need to tell ssh to forward the GIT_PUSH environment variable to the git server. If you don't have an ssh config file yet, create one. It is probably wise to put a

Host scm.dev*

line in front of the

SendEnv

line to restrict the scope of the setting. Under Windows, the file will be usually located in

"C:and Settingslt;user>sh\config"

, though apparently it is possible to set HOME like under Unix to change ssh's behavior. It is possible to run most of the checks locally before attempting to push- this is especially useful for the checks which are currently advisory only. See the

devtools/shell/git_post_commit_hook

script (it contains installation instructions).