Call for Discussion: New Project: Developer's Guide -- suggestion to separate information having different life cycles

[Joe Darcy]

Hello,

Having penned a complementary "OpenJDK Developers' Guide" back in 2010 
[1], I wanted to offer a suggestion on structuring the new guide: 
separate information of different life cycles into different documents. 
For example, put any release-specific information into release-specific 
documents and put stable, mostly time-invariant information into the 
main developer's guide.

In the JDK code base, over the years we've recognized that hard-coded 
release values used in tests or the javadoc are often a maintenance 
burden. I think the same would be true of a developer's guide; the guide 
shouldn't necessarily need to be updated every six months (or three 
months) just because the feature releases have a six-month cadence and 
update releases come out every three months. [2]

HTH,

-Joe

[1] 
http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/OpenJdkDevelopersGuide.v0.777.html

This material was used to seed the CSR compatibility discussion years later:

https://wiki.openjdk.java.net/display/csr/Kinds+of+Compatibility

[2] HT Prof. Edsger W. Dijkstra on describing the Buxton Index in his 
essay "The strengths of the academic enterprise" 
(https://www.cs.utexas.edu/users/EWD/transcriptions/EWD11xx/EWD1175.html). 
To rephrase the suggestion: avoid shear stress in the guide by not 
mixing content with different Buxton indexes.