You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@thrift.apache.org by hc...@apache.org on 2015/02/05 12:18:39 UTC
thrift git commit: THRIFT-2724 - Coding standards template added all
over project
Repository: thrift
Updated Branches:
refs/heads/master 2f34da702 -> 3bc6424c7
THRIFT-2724 - Coding standards template added all over project
Client: All
Patch: Konrad Grochowski
This closes #371
Project: http://git-wip-us.apache.org/repos/asf/thrift/repo
Commit: http://git-wip-us.apache.org/repos/asf/thrift/commit/3bc6424c
Tree: http://git-wip-us.apache.org/repos/asf/thrift/tree/3bc6424c
Diff: http://git-wip-us.apache.org/repos/asf/thrift/diff/3bc6424c
Branch: refs/heads/master
Commit: 3bc6424c76c1c29da72fe16ad9d3014b09b02b0f
Parents: 2f34da7
Author: Konrad Grochowski <hc...@apache.org>
Authored: Wed Feb 4 16:43:26 2015 +0100
Committer: Konrad Grochowski <hc...@apache.org>
Committed: Thu Feb 5 12:15:19 2015 +0100
----------------------------------------------------------------------
.gitattributes | 1 +
CONTRIBUTING.md | 37 +++++++++-------
compiler/cpp/coding_standards.md | 4 ++
doc/coding_standards.md | 48 ++++++++++++++++++++
doc/committers.md | 83 +++++++++++++++--------------------
lib/as3/coding_standards.md | 1 +
lib/c_glib/coding_standards.md | 5 +++
lib/cocoa/coding_standards.md | 1 +
lib/cpp/coding_standards.md | 4 ++
lib/csharp/coding_standards.md | 6 +++
lib/d/coding_standards.md | 1 +
lib/delphi/coding_standards.md | 1 +
lib/erl/coding_standards.md | 1 +
lib/go/coding_standards.md | 1 +
lib/haxe/coding_standards.md | 1 +
lib/hs/coding_standards.md | 1 +
lib/java/coding_standards.md | 1 +
lib/javame/coding_standards.md | 1 +
lib/js/coding_standards.md | 1 +
lib/lua/coding_standards.md | 1 +
lib/nodejs/coding_standards.md | 1 +
lib/ocaml/coding_standards.md | 1 +
lib/perl/coding_standards.md | 1 +
lib/php/coding_standards.md | 1 +
lib/py/coding_standards.md | 7 +++
lib/rb/coding_standards.md | 1 +
lib/st/coding_standards.md | 1 +
lib/ts/coding_standards.md | 1 +
28 files changed, 149 insertions(+), 65 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/.gitattributes
----------------------------------------------------------------------
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..176a458
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1 @@
+* text=auto
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/CONTRIBUTING.md
----------------------------------------------------------------------
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f3074a4..a569fd7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,43 +3,46 @@
1. Make sure your issue is not all ready in the [Jira issue tracker](http://issues.apache.org/jira/browse/THRIFT)
1. If not, create a ticket describing the change you're proposing in the [Jira issue tracker](http://issues.apache.org/jira/browse/THRIFT)
1. Contribute your patch using one of the two methods below
-
+
### Contributing via a patch
-
+
1. Check out the latest version of the source code
-
- * git clone https://git-wip-us.apache.org/repos/asf/thrift.git thrift
+
+ * git clone https://git-wip-us.apache.org/repos/asf/thrift.git thrift
1. Modify the source to include the improvement/bugfix
-
- * Verify that you follow the same CodingStyle you see within the language you are working on
- * Verify that your change works by adding a unit test.
+
+ * Remember to provide *tests* for all submited changes
+ * When bugfixing: add test that will isolate bug *before* applying change that fixes it
+ * Verify that you follow [Thrift Coding Standards](/coding_standards) (you can run 'make style', which ensures proper format for some languages)
1. Create a patch from project root directory (e.g. you@dev:~/thrift $ ):
-
- * git diff > ../thrift-XXX-my-new-feature.patch
+
+ * git diff > ../thrift-XXX-my-new-feature.patch
1. Attach the newly generated patch to the issue
1. Wait for other contributors or committers to review your new addition
1. Wait for a committer to commit your patch
-
+
### Contributing via GitHub pull requests
1. Create a fork for http://github.com/apache/thrift
-1. Create a branch with the jira ticket number you are working on
+1. Create a branch for your changes
1. Modify the source to include the improvement/bugfix
-
- * Verify that you follow the same CodingStyle you see within the language you are working on
- * Verify that your change works by adding a unit test.
-1. Issue a pull request for your new feature
+ * Remember to provide *tests* for all submited changes
+ * When bugfixing: add test that will isolate bug *before* applying change that fixes it
+ * Verify that you follow [Thrift Coding Standards](/coding_standards) (you can run 'make style', which ensures proper format for some languages)
+
+1. Commit and push changes to your branch
+1. Issue a pull request with the jira ticket number you are working on in it's name
1. Wait for other contributors or committers to review your new addition
1. Wait for a committer to commit your patch
### More info
-
+
Plenty of information on why and how to contribute is available on the Apache Software Foundation (ASF) web site. In particular, we recommend the following:
-
+
* [Contributors Tech Guide](http://www.apache.org/dev/contributors)
* [Get involved!](http://www.apache.org/foundation/getinvolved.html)
* [Legal aspects on Submission of Contributions (Patches)](http://www.apache.org/licenses/LICENSE-2.0.html#contributions)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/compiler/cpp/coding_standards.md
----------------------------------------------------------------------
diff --git a/compiler/cpp/coding_standards.md b/compiler/cpp/coding_standards.md
new file mode 100644
index 0000000..ea08946
--- /dev/null
+++ b/compiler/cpp/coding_standards.md
@@ -0,0 +1,4 @@
+## Compiler Coding Standards
+
+ * When making small change / bugfix - follow style as seen in nearby code.
+ * When making major refactor and / or adding new feature - follow style for C++ library
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/doc/coding_standards.md
----------------------------------------------------------------------
diff --git a/doc/coding_standards.md b/doc/coding_standards.md
new file mode 100644
index 0000000..308100a
--- /dev/null
+++ b/doc/coding_standards.md
@@ -0,0 +1,48 @@
+# Thrift Coding Standards
+
+ Any fool can write code that a computer can understand.
+ Good programmers write code that humans can understand.
+ -- Martin Fowler, 1999
+
+The purpose of this document is to make everyone's life easier.
+
+It's easier when you read good, well formatted, with clearly defined purpose, code.
+But the only way to read clean code is to write such.
+
+This document can help achieve that, but keep in mind that
+those are not silver-bullet, fix-all-at-once rules. Just think about readability while writing code.
+Write code like you would have to read it in ten years from now.
+
+## General Coding Standards
+
+Thrift has some history. Not all existing code follows those rules.
+But we want to improve over time.
+When making small change / bugfix - like single line fix - do *not* refactor whole function.
+That disturbs code repository history.
+Whenever adding something new and / or making bigger refactoring
+ - follow those rules as strictly as you can.
+
+When in doubt - contact other developers (using dev@ mailing list or IRC).
+Code review is the best way to improve readability.
+
+### Basics
+ * Use spaces not tabs
+ * Use only ASCII characters in file and directory names
+ * Commit to repository using Unix-style line endings (LF)
+ On Windows:
+ git config core.autocrlf true
+ * Maximum line width - 100 characters
+ * If not specified otherwise in language specific standard - use 2 spaces as indent/tab
+
+### Comments
+ * Each file has to start with comment containing [Apache License](http://www.apache.org/licenses/LICENSE-2.0)
+ * Public API of library should be documented, preferably using format native for language specific documentation generation tools (Javadoc, Doxygen etc.)
+ * Other comments are discouraged - comments are lies. When one has to make comment it means one failed to write readable code. Instead of "I should write a comment here" think "I should clean it up"
+ * Do not leave "TODO/FIXME" comments - file [Jira](http://issues.apache.org/jira/browse/THRIFT) issue instead
+
+### Naming
+ Finding proper names is the most important and most difficult task in software development.
+
+## Language Specific Coding Standards
+
+For detailed information see `lib/LANG/coding_standards.md`
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/doc/committers.md
----------------------------------------------------------------------
diff --git a/doc/committers.md b/doc/committers.md
index 4606da5..b02edbe 100644
--- a/doc/committers.md
+++ b/doc/committers.md
@@ -1,67 +1,54 @@
## Process used by committers to review and submit patches
-1. Make sure that there is an issue for the patch(s) you are about to commit in our [Jira issue tracker]({{ conf.jira_url }})
-
+1. Make sure that there is an issue for the patch(s) you are about to commit in our [Jira issue tracker](http://issues.apache.org/jira/browse/THRIFT)
+
1. Check out the latest version of the source code
-
- * git clone https://git-wip-us.apache.org/repos/asf/thrift.git thrift
+
+ * git clone https://git-wip-us.apache.org/repos/asf/thrift.git thrift
1. Apply the patch
-
- * curl https://issues.apache.org/jira/... |git apply --ignore-space-change
-
- or
-
- * curl https://github.com/<GitHub User>/thrift/commit/<Commit ID>.patch |git apply --ignore-space-change
-
-
+
+ * curl https://issues.apache.org/jira/... |git apply --ignore-space-change
+
+ or
+
+ * curl https://github.com/<GitHub User>/thrift/commit/<Commit ID>.patch |git apply --ignore-space-change
+
+
1. Inspect the applied patch to ensure that all [Legal aspects on Submission of Contributions (Patches)](http://www.apache.org/licenses/LICENSE-2.0.html#contributions) are met
1. Run the necessary unit tests and cross language test cases to verify the patch
1. Commit the patch
- git --config user.name "Your Name"
- git --config user.email "YourApacheID@apache.org"
- git add -A
- git commit
-
-
+ git --config user.name "Your Name"
+ git --config user.email "YourApacheID@apache.org"
+ git add -A
+ git commit
+
1. The commit message should be in the format:
-
- THRIFT-###:<Jira description>
- Client: <component>
- Patch: <Name of person contributing the patch>
-
- Description of what was fixed or addressed.
-
- <%
- if this is a github pull request then copy the below block
- from the GitHub email that came to dev@ list, this will
- automatically close the GitHub pull request
- %>
- Github Pull Request: This closes #XX
- ----
- commit 1234567
- Author: docbrown <do...@example.com>
- Date: 1985-06-03T01:21:00Z
-
- fix for THRIFT-1234
-
- fix for THRIFT-1234 fixes the flux capacitor
+
+ THRIFT-###:<Jira description>
+ Client: <component>
+ Patch: <Name of person contributing the patch>
+
+ Description of what was fixed or addressed.
+
+ <%
+ if this is a github pull request then add below comment
+ to automaticaly close GitHub request.
+ %>
+ This closes #XX
1. Double check the patch committed and that nothing was missed then push the patch
- git status
- git show HEAD
- git push origin master
+ git status
+ git show HEAD
+ git push origin master
-
-1. Resolve the jira issue and set the following for the changelog
- * Component the patch is for
- * fixVersion to the current version on master
-
+1. Resolve the jira issue and set the following for the changelog
-
+ * Component the patch is for
+ * fixVersion to the current version on master
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/as3/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/as3/coding_standards.md b/lib/as3/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/as3/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/c_glib/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/c_glib/coding_standards.md b/lib/c_glib/coding_standards.md
new file mode 100644
index 0000000..fbe1acf
--- /dev/null
+++ b/lib/c_glib/coding_standards.md
@@ -0,0 +1,5 @@
+## C Glib Coding Standards
+
+Please follow:
+ * [Thrift General Coding Standards](/coding_standards)
+ * [GNOME C Coding Style](https://help.gnome.org/users/programming-guidelines/stable/c-coding-style.html.en)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/cocoa/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/cocoa/coding_standards.md b/lib/cocoa/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/cocoa/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/cpp/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/cpp/coding_standards.md b/lib/cpp/coding_standards.md
new file mode 100644
index 0000000..fac5056
--- /dev/null
+++ b/lib/cpp/coding_standards.md
@@ -0,0 +1,4 @@
+Please follow [General Coding Standards](/coding_standards)
+
+ * see .clang-format in root dir for settings of accepted format
+ * clang-format (3.5 or newer) can be used to automaticaly reformat code ('make style' command)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/csharp/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/csharp/coding_standards.md b/lib/csharp/coding_standards.md
new file mode 100644
index 0000000..9706d26
--- /dev/null
+++ b/lib/csharp/coding_standards.md
@@ -0,0 +1,6 @@
+## C# Coding Standards
+
+Please follow:
+ * [Thrift General Coding Standards](/coding_standards)
+ * [MSDN C# Coding Conventions](http://msdn.microsoft.com/en-us/library/ff926074.aspx)
+ * [C# Coding Guidelines](http://csharpguidelines.codeplex.com/)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/d/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/d/coding_standards.md b/lib/d/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/d/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/delphi/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/delphi/coding_standards.md b/lib/delphi/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/delphi/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/erl/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/erl/coding_standards.md b/lib/erl/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/erl/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/go/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/go/coding_standards.md b/lib/go/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/go/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/haxe/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/haxe/coding_standards.md b/lib/haxe/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/haxe/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/hs/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/hs/coding_standards.md b/lib/hs/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/hs/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/java/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/java/coding_standards.md b/lib/java/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/java/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/javame/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/javame/coding_standards.md b/lib/javame/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/javame/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/js/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/js/coding_standards.md b/lib/js/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/js/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/lua/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/lua/coding_standards.md b/lib/lua/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/lua/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/nodejs/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/nodejs/coding_standards.md b/lib/nodejs/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/nodejs/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/ocaml/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/ocaml/coding_standards.md b/lib/ocaml/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/ocaml/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/perl/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/perl/coding_standards.md b/lib/perl/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/perl/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/php/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/php/coding_standards.md b/lib/php/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/php/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/py/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/py/coding_standards.md b/lib/py/coding_standards.md
new file mode 100644
index 0000000..280f5e9
--- /dev/null
+++ b/lib/py/coding_standards.md
@@ -0,0 +1,7 @@
+## Python Coding Standards
+
+Please follow:
+ * [Thrift General Coding Standards](/coding_standards)
+ * Code Style for Python Code [PEP8](http://legacy.python.org/dev/peps/pep-0008/)
+
+When in doubt - check with <http://www.pylint.org/> or online with <http://pep8online.com>.
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/rb/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/rb/coding_standards.md b/lib/rb/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/rb/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/st/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/st/coding_standards.md b/lib/st/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/st/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)
http://git-wip-us.apache.org/repos/asf/thrift/blob/3bc6424c/lib/ts/coding_standards.md
----------------------------------------------------------------------
diff --git a/lib/ts/coding_standards.md b/lib/ts/coding_standards.md
new file mode 100644
index 0000000..d4751af
--- /dev/null
+++ b/lib/ts/coding_standards.md
@@ -0,0 +1 @@
+Please follow [General Coding Standards](/coding_standards)