From d66b7c71c0f564af97125254a1d89887926e549d Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Mon, 8 Jan 2024 11:09:39 -0500 Subject: [PATCH] refine style guide --- CONTRIBUTING.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3457f9a0..515bb29f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ If you are eager to contribute to a NetFoundry-managed open source project pleas ## Project Styles This project uses several programming languages. Each language has its own style guide specifying any language-specific -conventions and idioms. +conventions and idioms. The log formatting examples for Go are applicable to all languages. ### Markdown @@ -21,13 +21,33 @@ conventions and idioms. + This project uses [Go](https://golang.org/) language conventions. + Organize imports as a single block in alphabetical order without empty lines. -+ Begin log messages with a lowercase letter and do not end with punctuation. ++ Begin log messages with a lowercase letter and do not end with punctuation. This log formatting guidance applies to all languages, not only Go. + + Format log messages that report errors. + + ```go + logrus.Errorf("tried a thing and failed: %v", err) + ``` + + Format in-line information in informational log messages. + + ```go + logrus.Infof("the expected value '%v' arrived as '%v'", expected, actual) + ``` + + Format in-line information in error log messages. + + ```go + logrus.Errorf("the expected value '%v did not compute: %v", value, err) + ``` + + Format log messages with format strings and arguments like 'tried a thing and failed: %s'. ### Python + This project uses [Python](https://www.python.org/) language conventions PEP-8. + Use [flake8](https://flake8.pycqa.org/en/latest/) with [the configuration file](.flake8) committed to this repository to find formatting problems. ++ Use Go log formatting guidance for Python too. ### Docusaurus