RFR: Added section for newcomers [v2]

[Stuart Marks]

On Wed, 18 Nov 2020 08:19:16 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

>> src/index.md line 34:
>> 
>>> 32: 
>>> 33: Once the OCA is signed, please restrain your urge to create a PR just a little while longer. In order to prepare the community for your patch, please socialize your idea on the relevant [mailing lists](#mailing-lists). Java and the JDK are very popular products, and just about every Java developer out there has an idea or two for how to enhance something. And (obviously not referring to you) believe it or not, not every idea is a good idea. Even though many ideas are indeed good, we must be quite restrictive on what we actually include into the JDK. There are many reasons for this. Stability is one. Any change that goes into the source code risks introducing bugs. This means that the added value of your change must outweigh the added risk of it. The code must be maintained for a foreseeable future even if you as the original developer decides not to do so. This means that the added value of your change must outweigh the added maintenance burden of it. All changes to the Java 
 programming language are visible to a large developer community. Any change you do will require a very large number of developers around the world to spend time to understand your change. Again, the added value of your change must outweigh the cost for all those developers' time. For reasons like these it's quite possible that your change, even though it adds value to you, isn't deemed to add enough value to the larger community.
>>> 34: 
>> 
>> This is good stuff. There are rather more issues than are listed here; I'd suggest listing them but providing fewer details. A full exploration of this issue could be its own essay or article! Here's some text that covers the issues I can think of (which includes some of the ones mentioned already). This material can probably replace the section of text above starting at "Stability is one."
>> 
>> * Hidden constraints and assumptions. Many sections of code have constraints and assumptions that aren't necessarily visible at first glance. This might preclude certain changes, even those that might seem obvious.
>> 
>> * Stability and quality. The JDK is used by millions of developers and as a widely deployed commercial product, it is held to a high standard of quality. Changes should include tests where practicable, and core tests should be kept passing at all times. The value of the change should outweigh the risk of introducing a bug.
>> 
>> * Maintainability. Any new feature or code change will need to be maintained in the JDK essentially forever, thus imposing a maintenance burden on future maintainers. The code might still be in use long after you and the people who reviewed it have moved on. The new maintainers must be able to understand how to fix a bugs in this code.
>> 
>> * Complexity. Each new feature interacts with all the existing features, which can result in geometric growth of the interactions among features if features are added unchecked. Sometimes we avoid adding a new feature, even if it seems like an obvious thing to add, if that feature would make it difficult to add a more important feature in the future.
>> 
>> * Adherence to specifications. Much of the JDK is governed by a series of specifications, in particular the _Java Language Specification_, the _Java Virtual Machine Specification_, and the _Java API Specification_ ("javadocs"). All changes must be checked and tested carefully to ensure that they don't violate these specifications.
>> 
>> * Javadoc comments are specifications. The _Java API Specification_ is authored in the form of javadoc comments, so even apparently innocuous changes to comments can be quite significant. It's not always easy to tell what comments are part of the specification and what parts are merely code comments. Briefly, documentation comments on public packages, classes, and class members of exported modules are specifications.
>> 
>> * Specification changes. It is possible to change the API specifications, and this is done regularly. However, these changes require even more scrutiny than code changes. This extra review is handled by the [CSR process](https://wiki.openjdk.java.net/display/csr/Main). Specifications are written in stylized, somewhat formal language, and they don't simply describe what the code does. Writing specifications is a separate skill from coding.
>> 
>> * Compatibility. Changes should also adhere to high standards of binary, source, and behavioral compatibility. The compatibility impact of apparently innocuous changes is sometimes startling.
>
> @stuart-marks I think all your bullet points here are very good. But I think they'll be just too much in this kind of "TL;DR" introduction that Jesper is trying to write here. Perhaps a solution is to add a heading like "Why is it so hard to contributes changes to OpenJDK?" (or maybe phrased somewhat less contentiously) further down the file. 
> 
> And keep this part short; perhaps even shorter than it is now, something like:
> 
> `
> Once the OCA is signed, please restrain your urge to create a PR just a little while longer. In order to prepare the community for your patch, please socialize your idea on the relevant [mailing lists](#mailing-lists). Due to a variety of reasons, getting a patch into OpenJDK projects is not like in a normal, small, GitHub hobbyist project. To understand the criteria by which your patch is going to be judged,  please read [Submit well-motivated changes](#submit-well-motivated-changes). In short, code contributed to the JDK will be judged by its stability, maintainability, compatibility, complexity, and effects on specifications. If you do not understand the constraints for acceptance, you might be surprised when your PR is rejected.
> `
> 
> And then take Stuarts list above and merge it with Jespers original prose about how Java is a popular product and that all changes affect millions of developers into a separate "Submit well-motivated changes" section after the mailing lists, or so.

Hm yes, that did turn into a wall of text, didn't it? :-) Maybe for the paragraph itself, just pull off the bullet headers and list them as reasons, without further elaboration here. So the second part of the paragraph might read something like,

> Even though many ideas are indeed good, we must be quite restrictive on what we actually include into the JDK. There are many reasons for this, including: hidden constraints and assumptions, stability and quality, maintainability, compatibility, and conformance to specifications.

No need to list every one of the bullet items; the above is probably enough.

We can discuss the need for a "Why is it so hard to contribute to OpenJDK?" separately. I suspect we'll need something like that sooner or later. Meanwhile, the text I wrote will be here and we can from copy it later.

-------------

PR: https://git.openjdk.java.net/guide/pull/38