From 4643d95f26b9e985acf573f77ae453fd2aa20f2a Mon Sep 17 00:00:00 2001 From: A_D Date: Thu, 27 May 2021 10:27:25 +0200 Subject: [PATCH] Add HACK/MAGIC/WORKAROUND comments --- Contributing.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/Contributing.md b/Contributing.md index 0f57c12c..d1541369 100644 --- a/Contributing.md +++ b/Contributing.md @@ -325,6 +325,21 @@ literals. Doc strings are preferred on all new modules, functions, classes, and methods, as they help others understand your code. We use the `sphinx` formatting style, which for pycharm users is the default. +### Mark hacks and workarounds with a specific comment + +We often write hacks or workarounds to make EDMC work on a given version or around a specific bug. +Please mark all hacks, workarounds, magic with one of the following comments, where applicable: +``` +# HACK $elite-version-number | $date: $description +# MAGIC $elite-version-number | $date: $description +# WORKAROUND $elite-version-number | $date: $description +``` + +The description should cover exactly why the hack is needed, what it does, what is required / expected for it to be removed. +Please be verbose here, more info about weird choices is always prefered over magic that we struggle to understand in six months. + +Additionally, if your hack is giant, please include a `# HACK END` or similar comment to indicate the end of the hack. + --- ## Git commit conventions