diff options
28 files changed, 149 insertions, 65 deletions
diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..176a458f9 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +* text=auto diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f3074a4cc..a569fd729 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) diff --git a/compiler/cpp/coding_standards.md b/compiler/cpp/coding_standards.md new file mode 100644 index 000000000..ea089467e --- /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 diff --git a/doc/coding_standards.md b/doc/coding_standards.md new file mode 100644 index 000000000..308100ab0 --- /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` diff --git a/doc/committers.md b/doc/committers.md index 4606da5f1..b02edbe00 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 <docbrown@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 diff --git a/lib/as3/coding_standards.md b/lib/as3/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/as3/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/c_glib/coding_standards.md b/lib/c_glib/coding_standards.md new file mode 100644 index 000000000..fbe1acf27 --- /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) diff --git a/lib/cocoa/coding_standards.md b/lib/cocoa/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/cocoa/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/cpp/coding_standards.md b/lib/cpp/coding_standards.md new file mode 100644 index 000000000..fac5056fb --- /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) diff --git a/lib/csharp/coding_standards.md b/lib/csharp/coding_standards.md new file mode 100644 index 000000000..9706d2690 --- /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/) diff --git a/lib/d/coding_standards.md b/lib/d/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/d/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/delphi/coding_standards.md b/lib/delphi/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/delphi/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/erl/coding_standards.md b/lib/erl/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/erl/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/go/coding_standards.md b/lib/go/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/go/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/haxe/coding_standards.md b/lib/haxe/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/haxe/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/hs/coding_standards.md b/lib/hs/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/hs/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/java/coding_standards.md b/lib/java/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/java/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/javame/coding_standards.md b/lib/javame/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/javame/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/js/coding_standards.md b/lib/js/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/js/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/lua/coding_standards.md b/lib/lua/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/lua/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/nodejs/coding_standards.md b/lib/nodejs/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/nodejs/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/ocaml/coding_standards.md b/lib/ocaml/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/ocaml/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/perl/coding_standards.md b/lib/perl/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/perl/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/php/coding_standards.md b/lib/php/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/php/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/py/coding_standards.md b/lib/py/coding_standards.md new file mode 100644 index 000000000..280f5e95e --- /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>. diff --git a/lib/rb/coding_standards.md b/lib/rb/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/rb/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/st/coding_standards.md b/lib/st/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/st/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) diff --git a/lib/ts/coding_standards.md b/lib/ts/coding_standards.md new file mode 100644 index 000000000..d4751af05 --- /dev/null +++ b/lib/ts/coding_standards.md @@ -0,0 +1 @@ +Please follow [General Coding Standards](/coding_standards) |