Kim, I have to defer to Chris on this matter. His rationale for removing the code makes sense. Better to make it really clear what it functions/methods to use.
My feeling is initially during the refactoring effort there will be many deprecated functions, but once we are on a stable release of the software there should be far less code to remove/replace. -Cameron On Fri, Jun 7, 2013 at 4:57 PM, Mattmann, Chris A (398J) < [email protected]> wrote: > 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 > > > > > > > > > >
