RFR: Added section for newcomers [v4]

[Jesper Wilhelmsson]

On Thu, 19 Nov 2020 01:40:59 GMT, David Holmes <dholmes at openjdk.org> wrote:

>> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   why is my change rejected?
>
> src/index.md line 29:
> 
>> 27: ### 1. Sign the OCA
>> 28: 
>> 29: Oracle are the stewards of the OpenJDK project, and owns the Java brand. In order to make your patch available for review you must first sign the [Oracle Contributor Agreement](https://www.oracle.com/technical-resources/oracle-contributor-agreement.html) (OCA). This agreement gives Oracle and you as a contributor joint copyright interests in the code. You will retain your copyright while also granting those rights to Oracle.
> 
> s/Oracle are/Oracle is/

Fixed

> src/index.md line 39:
> 
>> 37: ### 3. Find a sponsor
>> 38: 
>> 39: Socializing your change on the mailing lists also prevents the surprise that would otherwise make the community choke on their morning coffee when they see a huge patch in a new, unknown PR. As a new developer in the community you'll need to make a few friends that agrees with your change. There are many good reasons to make friends, but the one relevant here is that for your first changes you'll need a sponsor to approve your work. This is in addition to the reviewers (but can be the same person). The sponsor takes on a larger responsibility for your change than the reviewers, and may need to defend the change in case of later problems. For this reason it's important that the sponsor understands all the details of your proposed change. Making people choke on their morning coffee isn't the way to make friends.
> 
> s/agrees/agree/
> 
> I don't think "approve" is the right way to categorise what the sponsor does. The sponsor facilitates the integration of the PR by potentially doing a range of tasks (JBS updates, additional testing). It is usual for a sponsor to also be a reviewer of a change and thus familiar with it, but it is not a requirement. I also disagree that the sponsor may have to defend a change - that is the Reviewers role. Sponsoring can be viewed as a purely administrative rather than technical role.

Re-phrased.

> src/index.md line 65:
> 
>> 63: * **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.
>> 64: 
>> 65: * **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.
> 
> s/practicable/practical/
> s/be kept passing/pass/
> Perhaps add ", or performance regression." to the end?

Fixed.

> src/index.md line 93:
> 
>> 91: > [`mail.openjdk.java.net`](https://mail.openjdk.java.net/mailman/listinfo)
>> 92: 
>> 93: 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. You're also strongly encouraged to use your real name on the mailing lists. This adds to the professional tone of your email. Postings from anonymized mailboxes risk being seen as spam. If you do work in the OpenJDK on behalf of your employer, please also list this affiliation.
> 
> Just an observation but as much of the mailing list traffic is generated via PR's and github we have a new problem with identity because Github user names can be completely obscure, and unlike a lot of email addresses, don't even show which company you may represent. Mapping from a Github user name to anything that actually identifies the person can be difficult.

True. I've added a sentence about including your GitHub user name as well.

> src/index.md line 27:
> 
>> 25: In many GitHub projects the standard way to propose a change is to create a pull request (PR) and discuss the patch in the PR. For OpenJDK projects the situation is somewhat different. First of all, the JDK and the surrounding tooling developed in the OpenJDK projects are part of commercial products maintained and sold by many companies. The JDK is installed on billions of devices and there are many millions of developers out there who use Java. For this reason there must be several safety checks before a change is made.
>> 26: 
>> 27: ### 1. Sign the OCA
> 
> The OCA is not required for very small/trivial changes. Not sure if the tooling allows for that fact?
> ref: http://openjdk.java.net/bylaws#participant

I don't see how the tooling could identify a trivial change given that even we humans have problems doing that sometimes :-)  I'll leave that out for now.

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

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