From 5a26bc372b3e0825cff83f92c54d05990dcb6766 Mon Sep 17 00:00:00 2001 From: George Shaw Date: Wed, 18 Oct 2017 17:41:03 -0500 Subject: [PATCH 1/2] updated contributing for better contributing instructions and issue_template style --- CONTRIBUTING.md | 42 +++++++++++++++++++++++++++++++++++++++++- ISSUE_TEMPLATE.md | 14 ++++++++++---- 2 files changed, 51 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1f600ad..6e999f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1 +1,41 @@ -# Todo +# Contributing to gPanel + +Todo general paragraph... + +## Stylistic & Conventions Guidelines + +We follow all naming and style conventions that are officially put out by the developers of Go themselves. All of these rules and conventions can be found in their [Effective Go](https://golang.org/doc/effective_go.html) tutorial. + +As this project is open source we do encourage commenting wherever may be necessary and require comments for all function declarations. The reason this is important is because it will increase productivity to whoever wants to come along and either add to or improve your code later on. + +### Examples of Well-documented Code + +```go +/* + A function used to add two integers who must be positive + + @param one int + The first integer term of the to-be sum, must be positive + @param two int + The second integer term of the to-be sum, must be positive + + @return int + The sum of the two input integers + @return error + The resulting error, if there is none it returns as nil + + Known Problems: Can't handle negative integers +*/ +func addTwoPositiveIntegers(one int, two int) (int, error) { + var answer int; + + if one < 0 || two < 0 { + return answer, errors.New("One or both of the input integers are negative") + } else { + answer = one + two + return answer, nil + } +} +``` + +This is how a typical function block comment should look. A short description of the function, followed by parameter explanations, then return explanations, and finally, if applicable, a "Known Problems" section. The known problems section is important because it is an easy way to set a flag of sorts for other contributors to come and fix what you couldn't figure out or didn't have time to do. diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md index a4297a3..2f8934c 100644 --- a/ISSUE_TEMPLATE.md +++ b/ISSUE_TEMPLATE.md @@ -1,7 +1,13 @@ -Severity level (1-10): +### Severity level (1-10): -Files/Directories Involved: -Description: -Personal Comments: +### Files/Directories Involved: + + + +### Description: + + + +### Personal Comments: From 541149d6ad9137cbf4f4c53bf39d5e2539fdebb7 Mon Sep 17 00:00:00 2001 From: George Shaw Date: Wed, 18 Oct 2017 17:43:08 -0500 Subject: [PATCH 2/2] added function blocks header to examples of well documented code in contributing.md --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6e999f1..167f813 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,8 @@ As this project is open source we do encourage commenting wherever may be necess ### Examples of Well-documented Code +#### Function Blocks + ```go /* A function used to add two integers who must be positive