RFR: Added section for newcomers [v2]

Wed Nov 18 06:11:08 UTC 2020

On Tue, 17 Nov 2020 21:18:25 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Added a section to the introduction to set the expectations for new developers in the OpenJDK.
>> 
>> I also moved the mail list section up since it's also relevant in this context and should (imho) be the first thing to learn about when thinking about joining the community.
>
> Jesper Wilhelmsson has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - OCA
>    
>    Co-authored-by: Magnus Ihse Bursie <mag at icus.se>
>  - Member of list
>    
>    Co-authored-by: Magnus Ihse Bursie <mag at icus.se>

Marked as reviewed by smarks (no project role).

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 pr
 ogramming 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.

src/index.md line 55:

> 53: > [`mail.openjdk.java.net`](https://mail.openjdk.java.net/mailman/listinfo)
> 54: 
> 55: The OpenJDK community is a friendly place. To keep it that way it's important to keep a professional tone in emails and be aware that the community is global. Many different people with different backgrounds collaborate in these lists. Even though English is the required language for all lists, many Participants speak other languages as their native language. A high tolerance for non-perfect English is expected from anyone joining these lists.

I'd also suggest that we state that it's preferred to use one's real name on the mailing lists. There are a couple people who post from anonymized mailboxes. That makes things difficult, as sometimes the responses look like spam. Also, I'd suggest that we suggest people list their professional affiliation if appropriate (that is, if they're actually doing work on the JDK on behalf of their employer).

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

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