Process to Handle Undocumented Functionality

Background

TWiki has some undocumented features. This is done for a number of reason, such as hiding legacy functionality where the syntax has changed at some point. The functionality is retained to "protect corporate investment (topic contents) from data corruption and incompatible changes".

Example of a renamed variables: The %URLENCODE{}% has been renamed to %ENCODE{}% in TWikiRelease01Sep2004. The old syntax is undocumented but still works.

Process to Document Undocumented Functionality

Undocumented functionality needs to be documented and accessible for testing somewhere, so that developers do not overlook it or remove it by accident.

Criteria: Every undocumented functionality needs to

1. be documented in the code
2. have unit tests and/or test cases.

Note: Test cases are still incomplete, this is for documented and undocumented functionality. If a feature has no test cases but is documented in the code, it should be discussed in Codev, and either (1) have written test cases within 4 weeks, or (2) removed from the code.

Process to Retire Undocumented Functionality

In some cases it is desirable to retire undocumented functionality, say to improve performance. A "nicer syntax" cannot be used as an excuse to retire undocumented functionality.

To retire an undocumented functionality it should:

1. be discussed in Codev and agreed on to retire
2. be announced in a TWikiProductionRelease as "to be retired in next release"
3. be retired in the next production release

Contributors: PeterThoeny, CrawfordCurrie - 17 Jan 2006

Discussions

Old discussion from 2006 removed; please see revision 14 for that discussion, which mainly related to an obscure heading syntax. I have retained what I think is the key generic observation to head the discussion below. -- CrawfordCurrie - 17 Apr 2008

I think that a deprecation strategy in the code should be discussed elsewhere. But even as far as documentation is concerned, I'd document whatever is working today if there is even the slightest chance that someone is using it. And there always is: Every absurdity has its champion.

Documentation for things that perhaps should never have existed but happen to work should go into a separate section, but it should be present. Coders need a hook where they can document that syntax A is not recommended but will continue to work until further notice, and that syntax B will need to be changed in some future release because it inhibits the development of a desirable enhancement. The latter - and only the latter - might provide a reason to discontinue a function. Making the code "more readable" never is, IMHO.

In my early years as a developer, I've always fought to get rid of undocumented features. But experience with customers has made me turn around completely: They are right, and I have been wrong.

-- HaraldJoerg - 13 Jan 2006

This topic has been raised again since the discussion in TWikibug:Item5118 relating to another piece of undocumented functionality that was innocently removed, and then reported as an "Urgent oh my god it's huge we're all going to die" bug.

• FJ

Harald's observation was never discussed or factored into the process, and needs to be discussed now in case this arises again.

Peter's process above suggests that If a feature has no test cases but is documented in the code, it should be discussed in Codev, and either (1) have written test cases within 4 weeks, or (2) removed from the code. It was probably the intention to apply this also to features that are undocumented in the code as well. This is obviously at odds with Harald's view. So who is right? What should the TWiki process be?

-- CrawfordCurrie - 17 Apr 2008

As I wrote on Item5118 it is a bit of a special case. I doubt we can make a generic rule that also covers a feature like this one.

I think costumer focussed common sense should never be traded for robotic business processes.

The rule in this topic makes good sense in 99% of the cases. Example is the %LANG% that I am about to document. If we had removed it and fixed the template problem another way have caused trouble for a lot of customers? Probably not. Should %LANG% be documented as a VarXXXX topic? No! Should it be documented? Yes - as a skin variable (which I will - I am working on it).

-- KennethLavrsen - 17 Apr 2008

Item5118 is an exception to this rule. I support the exception because (1) it never worked properly, (2) because of that nobody I am aware of is using it in production.

-- PeterThoeny - 18 Apr 2008

I believe it's essential that there is a documented process. Processes don't have to be robotic; but they do have to reflect the agreement in the community about how such situations are handled. I think Peter's process above is good; I'd like to see it clarified to cover totally undocumented features as well, and the 4 weeks is a bit short - a release meeting decision is required IMHO - but the central thrust of the process is sound. Under this process it is possible for anyone to "validate" the functionality described in TWikibug:Item5118 simply by writing a testcase that passes on 4.1.2 but fails on 4.2.0. What could be simpler?

-- CrawfordCurrie - 18 Apr 2008

I would not have a clue how to write a test case that checks for access rights before and after registration.

-- KennethLavrsen - 18 Apr 2008