Hey Kim, et al., Great list.
My suggestion: 1. Deprecated code is removed, not commented out (making it really hard to see what's really turned on or not). Before removing; 2. JIRA issue is created to remove code; with rationale from reasons below on Guidelines for deprecating. 3. Commit away 4. Along with #3, update CHANGES.txt file noting back incompat changes. Cheers, Chris ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Chris Mattmann, Ph.D. Senior Computer Scientist NASA Jet Propulsion Laboratory Pasadena, CA 91109 USA Office: 171-266B, Mailstop: 171-246 Email: [email protected] WWW: http://sunset.usc.edu/~mattmann/ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Adjunct Assistant Professor, Computer Science Department University of Southern California, Los Angeles, CA 90089 USA ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -----Original Message----- From: <Whitehall>, "Kim D (398J-Affiliate)" <[email protected]> Reply-To: "[email protected]" <[email protected]> Date: Thursday, June 6, 2013 9:40 PM To: "[email protected]" <[email protected]> Subject: Deprecation policy >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 > > > >
