Re-arrange sections in the Guide

[Jesper Wilhelmsson]

Hi Stuart,

I agree with everything you write here. In an attempt to address your first comment I have now created a PR with a section for newcomers: https://git.openjdk.java.net/guide/pull/38 <https://git.openjdk.java.net/guide/pull/38>

Please take a look and let me know if it matches your expectations or not.

The rewrite to git has started, but there is more work to do there. (Nothing has made it to a PR yet.)

As for the code conventions it seems unlikely that too much of that will end up in the Guide. I would like to use the introduction that Andreas wrote and then provide links to the external documents where ever they end up.

/Jesper

> On 13 Nov 2020, at 21:18, Stuart Marks <stuart.marks at oracle.com> wrote:
> 
> Overall, the organization makes sense to me. A couple items:
> 
> I think it would be good to have a section for newcomers. I not sure if it belongs here or in the "Contributing" document (which might have pointers to this document). My concern here is that the "GitHub standard way to do things" is to show up with a PR, and when people do so with OpenJDK, they run into a brick wall. Or several brick walls, actually:
> 
> - need to sign an OCA
> - need to find a sponsor
> - need to discuss whether something is a good idea
> - need to navigate differing review processes for different areas
> - need to file CSRs for certain changes
> - etc.
> 
> Of course all the repo stuff will need to be rewritten for Git. We can probably dispense with most if not all of the installation stuff and just refer people to a well-known place such as git-scm.com.
> 
> The "backing out" section also needs to be updated to use git.
> 
> We still need to decide whether the Code Conventions belong here or in a separate document.
> 
> s'marks
> 
> 
> On 11/4/20 3:22 AM, Jesper Wilhelmsson wrote:
>> Hi,
>> I'd like to re-arrange the sections in the Guide. I think that we should start with the mailing lists because that's where any OpenJDK interaction should start. "Change Planning and Guidelines" currently only have one section, "Fixing a bug", and I think that section is important enough to stand on it's own, so I suggest to skip the first header. JBS should have a section with more JBS stuff, and things like "Filing a bug" could fit there I think. If you look for information on how to file a bug I think it will be easier to find it if there is a section called JBS rather than "What Happens Next".
>> This is my suggestion for a new index:
>> • Introduction
>> • Mailing Lists
>> 	• Changing your email address
>> • Repositories
>> 	• Terminology and Naming Scheme
>> 	• Installing and Configuring Mercurial
>> 	• Cloning
>> • Building the OpenJDK  -- (In the making)
>> • Code Conventions
>> • JBS - JDK Bug System
>> 	• Filing a Bug
>> 	• JBS Label Dictionary
>> • Fixing a Bug
>> • Testing Changes
>> 	• JTReg
>> 		• Running OpenJDK JTReg Tests
>> 	• GTest
>> 		• Running OpenJDK GTests
>> 	• Excluding a Test
>> 		• ProblemListing jtreg tests
>> 		• Exclude jtreg tests using @ignore
>> 		• Dealing with JBS bugs for test exclusion
>> • Producing a Changeset
>> 	• Setting a JDK User Name
>> 	• Creating
>> 	• Merging
>> 	• Pushing
>> • Backing Out a Change
>> 	• How to work with JBS when a change is backed out
>> 	• How to work with mercurial when a change is backed out
>> • Code Owners
>> 	• Area mailing lists
>> 	• Directory to area mapping
>> • About this Guide
>> • Glossary
>> Let me know what you think.
>> Thanks,
>> /Jesper