From 585d5c4a47ba5afdfc41409b1ba68e1d4d6c8c4e Mon Sep 17 00:00:00 2001 From: Sambhav Kothari Date: Wed, 25 Jan 2017 01:25:04 +0530 Subject: [PATCH 1/3] Update CONTRIBUTING.md --- CONTRIBUTING.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 378da3dae..1495ce127 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,29 @@ -# Using GitHub +# Contributing to Picard -## The workflow +## Coding Style + +As most of the other projects written in Python, we use the [PEP 8](https://www.python.org/dev/peps/pep-0008/). Though, we ignore some of the recomendations: + +* E501 - Maximum line length (79 characters). The general limit we have is somewhere around 120-130. + +*Reccomended video: "[Beyond PEP 8 -- Best practices for beautiful intelligible code](https://www.youtube.com/watch?v=wf-BqAjZb8M)" by Raymond Hettinger at PyCon 2015, which talks about the famous P versus NP problem.* + +The general idea is to make the code within a project consistent and easy to interpret (for humans). + +### Docstrings + +Unless the function is easy to understand quickly, it should probably have a docstring describing what it does, how it does it, what the arguments are, and what the expected output is. + +Most of our Python projects use ["Google-style" docstrings](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments). + + +## Git Work-flow We follow the "typical" GitHub workflow when contributing changes: 1. [Fork](https://help.github.com/articles/fork-a-repo/) a repository into your account. 2. Create a new branch and give it a meaningful name. For example, if you are going to fix issue PICARD-257, branch can be called `picard-257` or `preserve-artwork`. -3. Make your changes and commit them with a [good description](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). Your commit subject should be written in **imperative voice** and **sentence case**. With regards to the contents of the message itself, you don't need to provide a lot of details, but make sure that people who look at the commit history afterwards can understand what you were changing and why.* +3. Make your changes and commit them with a [good description](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). Your commit subject should be written in **imperative voice** and **sentence case**. With regards to the contents of the message itself, you don't need to provide a lot of details, but make sure that people who look at the commit history afterwards can understand what you were changing and why. 4. [Create](https://help.github.com/articles/creating-a-pull-request/) a new pull request on GitHub. Make sure that the title of your pull request is descriptive and consistent with the rest. If you are fixing issue that exists in our bug tracker reference it like this: `PICARD-257: Allow preserving existing cover-art tags`. **Not** `[PICARD-257] - Allow preserving existing cover-art tags` or `Allow preserving existing cover-art tags (PICARD-257)` or simply `PICARD-257`. 5. Make sure to provide a bug tracker link to the issue that your pull request solves in the description. 6. Do not make one big pull request with a lot of unrelated changes. If you are solving more than one issue, unless they are closely related, split them into multiple pull requests. It makes it easier to review and merge the patches this way. From be5eddb0c422472141bdd661371e44ddc93cd00d Mon Sep 17 00:00:00 2001 From: Sambhav Kothari Date: Wed, 25 Jan 2017 21:23:57 +0530 Subject: [PATCH 2/3] Add picard specific code guidelines to CONTRIBUTING.md --- CONTRIBUTING.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1495ce127..0fda4cb51 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,11 +2,11 @@ ## Coding Style -As most of the other projects written in Python, we use the [PEP 8](https://www.python.org/dev/peps/pep-0008/). Though, we ignore some of the recomendations: +As most of the other projects written in Python, we use the [PEP 8](https://www.python.org/dev/peps/pep-0008/). Though, we ignore some of the recommendations: * E501 - Maximum line length (79 characters). The general limit we have is somewhere around 120-130. -*Reccomended video: "[Beyond PEP 8 -- Best practices for beautiful intelligible code](https://www.youtube.com/watch?v=wf-BqAjZb8M)" by Raymond Hettinger at PyCon 2015, which talks about the famous P versus NP problem.* +*Recommended video: "[Beyond PEP 8 -- Best practices for beautiful intelligible code](https://www.youtube.com/watch?v=wf-BqAjZb8M)" by Raymond Hettinger at PyCon 2015, which talks about the famous P versus NP problem.* The general idea is to make the code within a project consistent and easy to interpret (for humans). @@ -16,6 +16,12 @@ Unless the function is easy to understand quickly, it should probably have a doc Most of our Python projects use ["Google-style" docstrings](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments). +### Picard specific code + +Picard has some auto-generated `picard/ui/ui_*.py` PyQt UI related files. Please do not change them directly. To modify them, use Qt-Designer to edit the `ui/*.ui` and use the command `python setup.py build_ui` to generate the corresponding `ui_*.py` files. + +We use camel-case to name all functions and variables except for the pre-generated PyQt functions/variables. + ## Git Work-flow From 5d603c1b183d8a7f0206408edbb5f15759089ccd Mon Sep 17 00:00:00 2001 From: Sambhav Kothari Date: Wed, 25 Jan 2017 21:36:10 +0530 Subject: [PATCH 3/3] Add guideline for i18n --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0fda4cb51..c49906528 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,6 +22,7 @@ Picard has some auto-generated `picard/ui/ui_*.py` PyQt UI related files. Please We use camel-case to name all functions and variables except for the pre-generated PyQt functions/variables. +`gettext` and `gettext-noop` have been built-in the Picard code as `_` and `N_` respectively to provide support for internationalization/localization. You can use them without imports across all of Picard code. Make sure to mark all displayable strings for translation using `_` or `N_` as applicable. You can read more about python-gettext [here](https://docs.python.org/2/library/gettext.html). ## Git Work-flow