Dear All, Working on metrics.py stuff week, the question about a deprecation policy came up. So I thought to summarize the issues we came across with some suggestions on how to handle them as a means of starting the process about a deprecation policy.
Attached below are those thoughts for your feedback. Best regards, Kim ______ Workflow of deprecating code --- Committer duties --- 1 comment the code out (but allow it to be callable so the user can see the print statement). Add a DocString and Print statement accordingly from guidelines below. 2 If the function being deprecated has the same name as the new one, append "Deprecated" to the name. (KDW: this will prevent naming issues…but how would this influence the design?) 3 Announce deprecation updates when committing code for review. 4 Update the user community of the deprecation if accepted.(wiki update??) 4 Deprecation log? Instead of appending on to CHANGES.txt should we create a log for when functions have been removed between releases? --- End committer duties?--- 5 After ## of releases, remove the entire function from the code base. 6 Announce the removal to the user base. Guidelines on when to deprecate code 1 the functionality has been replaced by a more powerful and/or general alternative. Action for the DocString - Deprecated :: Replace by newFunction Print statement in function - Warning: Replace by newFunction 2 the code contained inefficiencies and/or has been succinctly rewritten Action for the DocString - Deprecated :: Print statement in function - Warning: This function inefficiently used resources and has been replaced by newFunction 3 the code contains workflow flaws e.g. may be calling functions that no longer exists Action for the DocString - Deprecated :: Design flow issue as of version ##. Replace by newFunction Print statement in function - Warning: This function generates design flaws as of version ## and is replaced by newFunction 4 the functionality is no longer required i.e. it is obsolete in the current version Action for the DocString - Deprecated :: Obsolete as of version ## Print statement in function - Warning: Obsolete as of version ##. Replaced by newFunction 5 the code contained inconsistencies regarding the code standard and was rewritten Action for the DocString - Deprecated :: Did not meet linting standards. Use functionName for this functionality. Print statement in function - Warning: Did not meet linting standards and was replaced by newFunction
