THRIFT-2724 - Coding standards template added all over project
Client: All
Patch: Konrad Grochowski
This closes #371
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`
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 <docbrown@example.com>
- Date: 1985-06-03T01:21:00Z
- fix for THRIFT-1234
+ THRIFT-###:<Jira description>
+ Client: <component>
+ Patch: <Name of person contributing the patch>
- fix for THRIFT-1234 fixes the flux capacitor
+ 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
-
-
-
+ * Component the patch is for
+ * fixVersion to the current version on master