Split up the monolithic index.md, take two

Makefile

@@ -7,14 +7,28 @@ endef
 
 TITLE := The OpenJDK Developers' Guide
 
-ALL_MD := $(wildcard src/*.md)
-ALL_FOOTER := $(patsubst src/%.md, build/support/footers/%.html, $(ALL_MD))
-ALL_RESULT := $(patsubst src/%.md, build/dist/%.html, $(ALL_MD))
+LEGACY_MD := $(wildcard src/*.md)
+LEGACY_FOOTER := $(patsubst src/%.md, build/support/footers/%.html, $(LEGACY_MD))
+LEGACY_RESULT := $(patsubst src/%.md, build/dist/%.html, $(LEGACY_MD))
+
+GUIDE_CHAPTERS := $(shell cat src/toc.conf)
+GUIDE_CHAPTER_FILES := $(addprefix src/guide/, $(GUIDE_CHAPTERS))
+GUIDE_CONCATENATED := build/support/index.md
+GUIDE_FOOTER := build/support/footers/index.html
+GUIDE_UTF8 := build/support/utf-8/index.html
+GUIDE_RESULT := build/dist/index.html
+
+ALL_RESULT := $(LEGACY_RESULT) $(GUIDE_RESULT)
 
 UTF8_HTML := $(patsubst build/dist/%.html, build/support/utf-8/%.html, $(ALL_RESULT))
 
+FOUND_GUIDE_CHAPTERS := $(wildcard src/guide/*.md)
+ifneq ($(sort $(FOUND_GUIDE_CHAPTERS)), $(sort $(GUIDE_CHAPTER_FILES)))
+  $(error "The guide chapters in src/guide do not match the chapters in src/toc.conf")
+endif
+
 ifneq ($(DEBUG_MAKE),)
-  .SECONDARY: $(ALL_FOOTER) $(UTF8_HTML)
+  .SECONDARY: $(LEGACY_FOOTER) $(GUIDE_CONCATENATED) $(GUIDE_FOOTER) $(UTF8_HTML)
 endif
 
 MERMAID ?= $(shell command -v mermaid-filter 2> /dev/null)
@@ -52,6 +66,22 @@ RunPandoc = \
 ConvertToLatin1 = \
 	sed -e 's/ charset=utf-8//' $1 | iconv -f UTF-8 -t ISO-8859-1 > $2
 
+$(GUIDE_CONCATENATED): $(GUIDE_CHAPTER_FILES)
+	rm -f $@.tmp
+	$(foreach s, $^, \
+		cat $s >> $@.tmp $(NEWLINE) \
+		printf "\n" >> $@.tmp $(NEWLINE) \
+	)
+	mv $@.tmp $@
+
+$(GUIDE_FOOTER): $(GUIDE_CONCATENATED)
+	mkdir -p build/support/footers
+	$(call GenerateFooter, $@, $(call GetHash, $(GUIDE_CHAPTER_FILES)), src/guide)
+
+$(GUIDE_UTF8): $(GUIDE_CONCATENATED) $(GUIDE_FOOTER)
+	mkdir -p build/support/utf-8
+	$(call RunPandoc, $<, $@)
+
 build/support/footers/%.html: src/%.md
 	mkdir -p build/support/footers
 	$(call GenerateFooter, $@, $(call GetHash, $<), $<)

src/guide/about-this-guide.md

@@ -0,0 +1,5 @@
+# About This Guide
+
+This guide is being maintained through the [OpenJDK Developers' Guide Project](https://openjdk.java.net/census#guide). The [source repository](https://github.com/openjdk/guide) is available at GitHub. The revision hash at the bottom of each page refers to the latest change that modified that particular page.
+
+Comments and questions may be sent to [guide-dev (at) openjdk.java.net](mailto:guide-dev-at-openjdk.java.net). Please let us know if there's anything in the guide that isn't clear.

src/guide/backporting.md

@@ -0,0 +1,92 @@
+# Backporting
+
+::: {.box}
+[Quick Links]{.boxheader}
+
+* [Push approval for JDK updates](https://openjdk.java.net/projects/jdk-updates/approval.html)
+* [Skara documentation on backports](https://wiki.openjdk.java.net/display/SKARA/Backports)
+:::
+
+Development of the latest version of the JDK often results in bug fixes that might be interesting to include in some of the JDK update releases still being maintained. Moving a fix from a more recent release train (e.g. JDK 17) to an older release train (e.g. JDK 11) is called *backporting*.
+
+The guideline for what to backport into a specific update release will vary over the lifetime of that release. Initially more fixes are expected to be backported as new features and large changes introduced in a mainline release stabilize. Over time the focus will shift from stabilization to keeping it stable - the release will go into maintenance mode. This means that bug fixes that require larger disruptive changes are more likely to be made in mainline and backported to more recent release trains only, and not to older release trains.
+
+Over time it's likely that the code base will diverge between mainline and any given update release, and the cost of backporting will increase. The cost in this case is not only the effort needed to perform the actual backport, but also the cost inferred by bugs introduced by the backport. This should be taken into consideration when deciding if a change should be backported or not. For more details on how to reason around what to backport, [this email from JDK 8 Updates Project lead Andrew Haley](https://mail.openjdk.java.net/pipermail/jdk8u-dev/2020-June/012002.html) has some guidelines for JDK 8u. The reasoning in this mail is specific to JDK 8u, but will in general apply to any JDK release in maintenance mode.
+
+Any change that originally required a CSR will require a new CSR to be backported unless the backport was covered by the initial CSR. Changes to Java SE specifications cannot be made in an update release without a Java SE Maintenance Release. CSR-related issues affect interfaces and behavior and must be very carefully scrutinized.
+
+## Working with backports in JBS
+
+::: {.box}
+[Terminology]{.boxheader}
+
+Main issue - The top issue in a backport hierarchy. Eg. [JDK-8272373](https://bugs.openjdk.java.net/browse/JDK-8272373) is a main issue, while [JDK-8277498](https://bugs.openjdk.java.net/browse/JDK-8277498) and [JDK-8277499](https://bugs.openjdk.java.net/browse/JDK-8277499) are backport issues of this main issue.
+:::
+
+::: {style="text-align:center;"}
+~~~{.mermaid caption="Example of backport hierarchy" format=svg theme=neutral}
+graph TD
+  main(JDK-8272373)
+  backport1(JDK-8277498)
+  backport2(JDK-8277499)
+  main --> |backport| backport1
+  main --> |backport| backport2
+~~~
+:::
+
+In general there's no need to create backport issues in JBS manually. All work that's done in JBS in preparation for a backport (requesting approvals etc) is done in the main issue. The backport issue will be created automatically by the bots when you integrate the change to the source code repository.
+
+There can be cases where it's desirable to create a backport issue before the fix is done, e.g. if a CSR needs to be filed. In these cases set the [Fix Version/s]{.jbs-field} of the backport to `N-pool`, where `N` is the release train the backport is targeting. E.g. `17-pool`. Please note that even if a backport issue is created ahead of time, all work done in JBS is still done in the main issue.
+
+Obviously it's possible to set the [Fix Version/s]{.jbs-field} to the exact release the backport is targeting, but this isn't recommended. When a change is pushed, the bots will look at the main issue as indicated in the PR title, and look for backports with the current `N.0.x` release version as [Fix Version/s]{.jbs-field}, if no such backport is found they will look for `N-pool`, and if that isn't found either, a new backport issue will be created. This means that if the backport has an exact [Fix Version/s]{.jbs-field} set, but is delayed and misses the release indicated by this [Fix Version/s]{.jbs-field}, a new backport issue is created with a small mess as the result.
+
+Setting the [Fix Version/s]{.jbs-field} of a backport to `N` is always wrong. JDK `N` has already been released (or you wouldn't be trying to backport to it) and can't get any more fixes.
+
+## Requesting approvals for backports
+
+In order to be allowed to push a change to one of the OpenJDK update development repositories (e.g. [`jdk17u-dev`](https://github.com/openjdk/jdk17u-dev)), an approval is required. The [official process for how to request push approval for a backport](https://openjdk.java.net/projects/jdk-updates/approval.html) describes in detail how to work with JBS when requesting approvals. In short, there's a label [jdk<release>u-fix-request]{.jbs-label} that should be added to the main JBS issue. Also put a motivation as to why the issue needs to be backported as a comment in the main issue. Once the label and motivation has been added, wait for the maintainers of the release to approve your request. The approval will be indicated with a label, [jdk<release>u-fix-yes]{.jbs-label}, added to the main issue.
+
+If the update release is in rampdown, changes are pushed to the release repository (e.g. [`jdk17u`](https://github.com/openjdk/jdk17u)). During rampdown the bar to get changes in are significantly higher and fixes need to be approved with [jdk<release>u-critical-request]{.jbs-label} / [jdk<release>u-critical-yes]{.jbs-label}.
+
+## Using the Skara tooling to help with backports
+
+The Skara tooling includes support for backports. [The official Skara documentation](https://wiki.openjdk.java.net/display/SKARA/Backports) describes in detail how to work with the tooling to create backport PRs on GitHub or using the CLI tools. As described in the documentation, the [`/backport`](https://wiki.openjdk.java.net/display/SKARA/Commit+Commands#CommitCommands-/backport) command can be used on a commit (not a PR!) to create the backport PR. If a backport PR is manually created, set the PR title to `Backport <original commit hash>`. This ensures that the bots will recognize it as a backport as opposed to a main fix specifically targeting an older release. One can tell whether or not the bots recognized a PR as a backport by the [backport]{.label} label being added if it's recognized.
+
+::: {.box}
+[To the top](#){.boxheader}
+:::
+
+## How to fix an incorrect backport creation in JBS
+
+If a main bug is targeted to a release and a fix referring to that main bug is pushed to a different release, then a backport bug is automatically created in JBS. Usually this is a "good thing", e.g., when you are backporting a fix to an earlier release, but not always... If the main bug is targeted to a later release (due to schedule planning), but someone finds the time to fix that bug in the current release, then the bug should be retargeted to the current release before pushing the fix. However, sometimes we forget to do that.
+
+Here's how to fix that:
+
+> ---
+>
+> In this example a fix was pushed to JDK N (a.k.a. the current release) while the JBS bug was targeted to JDK N+1 (a.k.a. a future release). The same procedure can be used in the opposite situation, when a fix has been pushed to JDK N+1 when the JBS bug was targeted to JDK N, by switching N and N+1 below. Remember, to keep the record clean for the future, what matters the most is that the bug id used in the commit comment is the main bug, and that the "backports" (regardless of if they are to earlier or later releases) are Backport type issues of that main issue. Also make sure there are never more than one Backport issue targeted to any given release.
+>
+> ---
+
+#. Reopen the _backport_ bug that was created automatically
+   * Use a comment like the following (in the reopen dialog):
+~~~
+Fix was pushed while main bug was targeted to 'N+1'. Reset the main bug to fixed in 'N', reset this bug to fix in 'na' and closed as 'Not An Issue' since JDK N+1 will automatically get this fix from JDK N later.
+~~~
+   * Change the [Fix Version/s]{.jbs-field} from 'N' to 'na'.
+   * Close the _backport_ bug as "Not an Issue".
+
+#. Clean up the _main_ bug
+   * Copy the push notification comment from the _backport_ bug to the _main_ bug, e.g.:
+~~~
+Changeset: 12345678
+Author: Duke <duke@openjdk.org>
+Date: 2020-10-23 15:37:46 +0000
+URL: https://git.openjdk.java.net/jdk/commit/12345678
+~~~
+   * Add a comment like the following to the _main_ bug:
+~~~
+Fix was pushed while main bug was targeted to 'N+1'. Reset the main bug to fixed in 'N' and copied the Robo Duke entry here.
+~~~
+   * Reset the _main_ bug [Fix Version/s]{.jbs-field} from 'N+1' to 'N'.
+   * Resolve the _main_ bug as "Fixed" in build "team" or in build "master" depending on where the fix was pushed - or to an actual build number if the change has already made it to a promoted build (look in the _backport_ bug if you are unsure). Pushes to 'openjdk/jdk' are fixed in build "master" and pushes to project repositories are fixed in build "team".

src/guide/building-the-jdk.md

@@ -0,0 +1,83 @@
+# Building the JDK
+
+::: {.box}
+[Quick Links]{.boxheader}
+
+* [Official build instructions](https://openjdk.java.net/groups/build/doc/building.html)
+* [openjdk/jdk GitHub project](https://github.com/openjdk/jdk)
+* [JDK 16 General-Availability Release](https://jdk.java.net/16/)
+:::
+
+The JDK build system is a fairly complex machine that has the ability to build anything from a single module to a complete shippable JDK bundle with various levels of debug capabilities, run tests, install your newly built JDK on your system, or cross-compile for some other system. The build uses `make` and a few other tools that you will have to install on your system before starting.
+
+The JDK supports incremental builds. This means that if you have a complete build and make changes in just a single part of the JDK (e.g. a module or part of the JVM), only that particular part needs to be rebuilt. So subsequent builds will be faster and you can always use a make target that results in a complete JDK image without having to worry about actually building the entire JDK every time. Please note that the incremental build do have limits in its understanding of what you change. For instance, if you change behaviors or conventions in one module there may be other parts of the JDK that implicitly depends on these without make's knowledge. For this reason you may have to rebuild several modules, or do a clean build if you change things that may have a wider impact.
+
+The examples below show the steps taken to build the JDK source code. Please see [Cloning the JDK](#cloning-the-jdk) for information on how to download it. These examples were written in the JDK 17 development time frame which is why the boot JDK used here is JDK 16. Note that the download links used here point to JDK 16 bundles. To build JDK N, use JDK N-1 as the boot JDK.
+
+The configure script will tell you what additional packages you need. In this first example several packages were needed since this build was performed on a clean Ubuntu installation. The configure script was run several times to get all the dependencies, but only the commands actually needed to get the JDK built are included in the log. This is just an example log, don't copy the `apt-get install` line. Instead run `sh ./configure` to see what packages you actually need on your system.
+
+    $ wget https://download.java.net/java/GA/jdk16/7863447f0ab643c585b9bdebf67c69db/36/GPL/openjdk-16_linux-x64_bin.tar.gz
+    $ tar xzf openjdk-16_linux-x64_bin.tar.gz
+    $ sudo apt-get install autoconf zip make gcc g++ libx11-dev libxext-dev libxrender-dev libxrandr-dev libxtst-dev libxt-dev libcups2-dev libfontconfig1-dev libasound2-dev
+    $ cd jdk
+    $ sh ./configure --with-boot-jdk=$HOME/jdk-16/
+    $ make images
+
+The built JDK can be found in `build/linux-x86_64-server-release/jdk`. The exact path depends on your build platform and selected configuration.
+
+The second example is from a clean (newly installed) Mac running MacOS Big Sur. Please note that in this case there are some steps taken outside of the terminal. First XCode and the XCode command line tools must be installed. It could be that the most recent version of XCode that you get from App Store is too new to have been properly tested with the JDK build. See [the JDK build instructions](https://github.com/openjdk/jdk/blob/master/doc/building.md#apple-xcode) for supported versions and more details in case you need to install an older version of XCode.
+In this example [Mac Ports](https://www.macports.org) is used to install `autoconf`. `autoconf` can also be installed using [Homebrew](https://brew.sh) and surely through other sources as well.
+
+    $ curl https://download.java.net/java/GA/jdk16.0.1/7147401fd7354114ac51ef3e1328291f/9/GPL/openjdk-16.0.1_osx-x64_bin.tar.gz --output openjdk-16.0.1_osx-x64_bin.tar.gz
+    $ tar xzf openjdk-16.0.1_osx-x64_bin.tar.gz
+    $ sudo port install autoconf
+    $ sh ./configure --with-boot-jdk=$HOME/jdk-16.0.1.jdk/Contents/Home
+    $ make images
+
+In this case the built JDK can be found in `build/macosx-x86_64-server-release/jdk`.
+
+## Configuration options
+
+The JDK build is extremely configurable. This list only contains the most basic configure options needed to get you started. Use `configure --help` to see a complete list of options.
+
+| Option | What it does   |
+|:-------|:-------|
+| `--with-boot-jdk` | Tell configure what boot JDK to use to build the Java libraries. |
+| `--with-debug-level` | Set the debug level. Available levels are `release`, `fastdebug`, `slowdebug`, `optimized`. |
+
+### Working with multiple configurations
+
+Through the configure flags you will select what configuration of the JDK to build. The name of the output directory for the build depends on this configuration. In the example above the JDK ended up in `linux-x86_64-server-release`. This means that we made a release build of a 64 bit linux x86 version of the server JDK. If we change some of these options the output directory will be affected accordingly.
+
+`--with-debug-level` is one example of a configure option that will change the output directory name. Sometimes it makes sense to have several different configurations in parallel. For example while debugging some code you might want to have both a debug build and a release build to be able to test it properly. The directory naming scheme makes this very easy. Simply configure and build the JDKs you need and they will end up next to each other in the build directory.
+
+In the example above we built a `release` image. To build a debug image as well we can configure with `--with-debug-level=slowdebug`. This will give us a JDK where for instance asserts in the JDK source code are enabled. To select which JDK to work with in later calls to `make` add `CONF=<configuration>`.
+
+    $ sh ./configure --with-boot-jdk=$HOME/jdk-16/ --with-debug-level=slowdebug
+    $ make CONF=slowdebug images
+    $ ls build/
+    linux-x86_64-server-release
+    linux-x86_64-server-slowdebug
+
+## Make targets
+
+`make images`, as used in the example above, will build a JDK image which is very close to what you'd get from any JDK provider. There are several other make targets you can use depending on what you're looking for. The table below contains some commonly used make targets.
+
+| Target | What it does |
+|:-------|:-------------|
+| `exploded-image` | This is the default make target that you'll get if you simply invoke `make`. |
+| `image` | Builds a complete JDK image. A good target to use if you want to build a JDK for general usage or if you want to test something closer to the shipping product. This can also be a good target to use if doing something which might have a build aspect to it. |
+| `<name>-image` | Build just the image for any of jdk, test, docs, symbols, etc. |
+| `reconfigure` | Re-runs the configure script with the same arguments as given the last time. |
+| `demos` | Builds the demos which for instance make it easy to test something UI related. |
+| `docs` | Builds the javadoc. Note that a number of classes in the javadoc API are generated during the build, so `make docs` might do more than simply invoke `javadoc`, depending on the state of your build. |
+| `java.base` | Builds the base module. You can (re)build any module with `make <module>`. |
+| `hotspot` | Builds the JVM. Note that the JVM depends on several other parts of the JDK, so `make hotspot` might build more than just the JVM, depending on the state of your build. |
+| `clean` | Removes all files generated by make, but not those generated by configure. Useful when doing significant renaming or refactoring which may confuse the incremental build. To clean out a specific module only use `make clean-<module>`. |
+| `dist-clean` | Removes all files, including configuration. |
+
+There are many other targets available as well. Use `make help` to find out more.
+
+::: {.box}
+[To the top](#){.boxheader}
+:::

src/guide/cloning-the-jdk.md

@@ -0,0 +1,100 @@
+# Cloning the JDK
+
+::: {.box}
+[Quick Links]{.boxheader}
+
+* [OpenJDK Mainline GitHub project](https://github.com/openjdk/jdk)
+* [Skara Documentation](https://wiki.openjdk.java.net/display/SKARA)
+:::
+
+The complete source code for the JDK is hosted at [GitHub](https://github.com). You can browse the code directly in the [openjdk/jdk repository](https://github.com/openjdk/jdk), or download the code for offline browsing, editing, and building using `git clone`.
+
+    $ git clone https://github.com/openjdk/jdk.git
+
+`openjdk/jdk` is the mainline JDK development repository where the next major release of the JDK is being developed. Other projects have their own repositories on GitHub.
+
+> ---
+>
+> Note that source may be available from other locations, for example `src.zip` from a full JDK distribution. However, OpenJDK contributions must use source from the appropriate OpenJDK GitHub repository since other source distributions may contain older code or code which differs due to licensing. Consult the Project's documentation or [mailing list](#mailing-lists) to determine the appropriate repository, development conventions, and helpful tools.
+>
+> ---
+
+If you intend to contribute patches, you should first *fork* the repository on GitHub and clone your own *personal fork* as shown below. To fork a project on GitHub, go to the GitHub project page and click the 'Fork' button in the upper right corner, then follow the on screen instructions.
+
+This is the typical development model:
+
+::: {style="text-align:center;"}
+~~~{.mermaid caption="Diagram of upstream repos and user's clone" format=svg theme=neutral}
+graph TD
+  subgraph GitHub
+    upstream(openjdk/jdk)
+    fork(OpenDuke/jdk)
+  end
+  upstream --> |fork| fork
+  fork --> |clone| local(local)
+  local --> |push| fork
+  fork --> |PR| upstream
+~~~
+:::
+
+Pushes to your personal fork can be made either using HTTPS or SSH. These examples assume you have an SSH key installed on GitHub. If this is the first time you clone your personal fork of an OpenJDK repository you may want to create an SSH key to use with it. See [Generating an SSH key] below. Once you have your personal fork and an SSH key to go with it, go ahead and clone.
+
+    $ git clone git@github.com:OpenDuke/jdk.git
+    $ cd jdk
+    $ git remote add upstream https://github.com/openjdk/jdk.git
+
+In the example above Duke cloned his personal fork of the JDK mainline repository using SSH. You should of course use your own GitHub username instead. Then, by adding a new *remote* named 'upstream', the clone is associated with [openjdk/jdk](https://github.com/openjdk/jdk). Doing this will allow the tooling to automatically create a PR on [openjdk/jdk](https://github.com/openjdk/jdk) whenever a change is pushed to the personal fork. The way that works is that once the change has been pushed to the personal fork, and you navigate to the [openjdk/jdk](https://github.com/openjdk/jdk) repository on GitHub, there will be a message saying that you just pushed a change and asking if you want to create a PR.
+
+The recommendation is to always create a new branch for any change you intend to implement. By doing that you can easily work on many different changes in parallel in the same code repository. Unless you know what you are doing, the recommendation is also to always base your new branch on the `master` branch.
+
+    $ git switch -c JDK-8272373 master
+
+Here we create a new branch called `JDK-8272373` based on the `master` branch and set the repository up to work in that new branch.
+
+`git switch` was introduced in Git version 2.23. For earlier versions of Git `git checkout` can be used instead. However it is always recommended to use the latest versions of all your tools when possible.
+
+::: {.box}
+More information about how to work with git and the dedicated tooling that is available for OpenJDK can be found in the [Project Skara Documentation](https://wiki.openjdk.java.net/display/SKARA). If you're new to git you can also read more about how to work with it in one of the many fine git tutorials available on the Internet. For instance the [Pro Git book](https://git-scm.com/book/en/v2). This guide doesn't aspire to become another git guide.
+:::
+
+## Generating an SSH key
+
+For security reasons you should always create new keys and use different keys with each repository you clone. The `ssh-keygen` command generates an SSH key. The `-t` option determines which type of key to create. `ed25519` is recommended. `-C` is used to add a comment in the key file, to help you remember which key it is. While it’s possible to use SSH without a passphrase, this is **strongly discouraged**. Empty or insecure passphrases may be reset using `ssh-keygen -p`; this doesn’t change the keys.
+
+    $ ssh-keygen -t ed25519 -C openjdk-jdk -f ~/.ssh/openjdk-jdk
+    Generating public/private ed25519 key pair.
+    Enter passphrase (empty for no passphrase):
+    Enter same passphrase again:
+    Your identification has been saved in /Users/duke/.ssh/openjdk-jdk.
+    Your public key has been saved in /Users/duke/.ssh/openjdk-jdk.pub.
+    The key fingerprint is:
+    SHA256:WS4jCQMtat75ZEue+so+Lgj7V/sdMtj1FTNkfNsCfHA openjdk-jdk
+    The key's randomart image is:
+    +--[ED25519 256]--+
+    |  ..       ..oE  |
+    |  ...       o+o .|
+    | . .o     .  o+.o|
+    |..   o . +    .=.|
+    |o . . o S o   .. |
+    |.. o +.+ + . .   |
+    |o.  *.+.+ . .    |
+    |o....=.  + .     |
+    | .=B=. .. .      |
+    +----[SHA256]-----+
+
+`~/.ssh/openjdk-jdk` is a text file containing your private ssh key. There's a corresponding public key in `~/.ssh/openjdk-jdk.pub` (as detailed in the example above). You should **never** share your private key. The *public* key on the other hand should be uploaded to GitHub. Follow the steps below to do that.
+
+* Go to the GitHub settings for your account by choosing "Settings" in the menu by your avatar in the upper right corner
+* Go to "SSH and GPG keys"
+* Click "New SSH key"
+* Title "OpenJDK" (or something else appropriate)
+* Paste the content of `~/.ssh/openjdk-jdk.pub` into the text field
+  * To get the content of the file you can for instance use `cat ~/.ssh/openjdk-jdk.pub`
+  * It will look something like this: `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIO8+egiIgWV+tE7LVVJmlR7WS2Lr3Fj7dXVo9HiasD6T openjdk-jdk`
+* Click "Add SSH key"
+
+Now you are ready to clone your [openjdk/jdk](https://github.com/openjdk/jdk) fork using SSH.
+
+::: {.box}
+[To the top](#){.boxheader}
+:::

src/guide/code-conventions.md

@@ -0,0 +1,12 @@
+# Code Conventions
+
+::: {.box}
+[Quick Links]{.boxheader}
+
+* [Java Code Conventions](https://www.oracle.com/technetwork/java/codeconvtoc-136057.html)
+* [HotSpot C++ Code Conventions](https://github.com/openjdk/jdk/blob/master/doc/hotspot-style.md)
+:::
+
+::: {.box}
+[To the top](#){.boxheader}
+:::

src/guide/code-owners.md

@@ -0,0 +1,201 @@
+# Code Owners
+
+This list is intended to make it easier to identify which email list to include in code reviews when making changes in different areas. The list may also help when assigning bugs based on which code they are found in. Please note that some directories may have been created or removed between releases. The intention here is to include directories that exists in mainline, LTS releases and other releases (post JDK 9) commonly being updated.
+
+## Area mailing lists
+
+* Build: [`build-dev@openjdk.java.net`](mailto:build-dev@openjdk.java.net)
+* Client
+  * AWT: [`awt-dev@openjdk.java.net`](mailto:awt-dev@openjdk.java.net)
+  * Beans: [`beans-dev@openjdk.java.net`](mailto:beans-dev@openjdk.java.net)
+  * Java 2D: [`2d-dev@openjdk.java.net`](mailto:2d-dev@openjdk.java.net)
+  * Java FX: [`openjfx-dev@openjdk.java.net`](mailto:openjfx-dev@openjdk.java.net)
+  * jpackage: [`core-libs-dev@openjdk.java.net`](mailto:core-libs-dev@openjdk.java.net)
+  * Sound: [`sound-dev@openjdk.java.net`](mailto:sound-dev@openjdk.java.net)
+  * Swing: [`swing-dev@openjdk.java.net`](mailto:swing-dev@openjdk.java.net)
+* Core Libs: [`core-libs-dev@openjdk.java.net`](mailto:core-libs-dev@openjdk.java.net)
+  * Net: [`net-dev@openjdk.java.net`](mailto:net-dev@openjdk.java.net)
+  * NIO: [`nio-dev@openjdk.java.net`](mailto:nio-dev@openjdk.java.net)
+* HotSpot: [`hotspot-dev@openjdk.java.net`](mailto:hotspot-dev@openjdk.java.net)
+  * Compiler: [`hotspot-compiler-dev@openjdk.java.net`](mailto:hotspot-compiler-dev@openjdk.java.net)
+  * GC: [`hotspot-gc-dev@openjdk.java.net`](mailto:hotspot-gc-dev@openjdk.java.net)
+  * Runtime: [`hotspot-runtime-dev@openjdk.java.net`](mailto:hotspot-runtime-dev@openjdk.java.net)
+  * JFR: [`hotspot-jfr-dev@openjdk.java.net`](mailto:hotspot-jfr-dev@openjdk.java.net)
+  * Serviceability: [`serviceability-dev@openjdk.java.net`](mailto:serviceability-dev@openjdk.java.net)
+* I18n: [`i18n-dev@openjdk.java.net`](mailto:i18n-dev@openjdk.java.net)
+* LangTools
+  * Amber Project: [`amber-dev@openjdk.java.net`](mailto:amber-dev@openjdk.java.net)
+  * Javac: [`compiler-dev@openjdk.java.net`](mailto:compiler-dev@openjdk.java.net)
+  * Javadoc: [`javadoc-dev@openjdk.java.net`](mailto:javadoc-dev@openjdk.java.net)
+  * JShell: [`kulla-dev@openjdk.java.net`](mailto:kulla-dev@openjdk.java.net)
+  * Panama Project: [`panama-dev@openjdk.java.net`](mailto:panama-dev@openjdk.java.net)
+  * Valhalla Project: [`valhalla-dev@openjdk.java.net`](mailto:valhalla-dev@openjdk.java.net)
+* Security: [`security-dev@openjdk.java.net`](mailto:security-dev@openjdk.java.net)
+
+## Directory to area mapping
+
+* `make` – Build team
+* `hotspot` – HotSpot
+  * `cpu` – Compiler, Runtime
+  * `jdk.*` – Compiler
+  * `os` – Runtime
+  * `os_cpu` – Compiler
+  * `share`
+    * `adlc` – Compiler
+    * `aot` – Compiler
+    * `asm` – Runtime
+    * `c1` – Compiler
+    * `ci` – Compiler
+    * `classfile` – Runtime
+    * `code` – Compiler
+    * `compiler` – Compiler
+    * `gc` – GC
+    * `include` – HotSpot
+    * `interpreter` – Runtime
+    * `jfr` – JFR
+    * `jvmci` – Compiler
+    * `libadt` – Compiler
+    * `logging` – Runtime
+    * `memory` – Runtime, GC
+    * `metaprogramming` – Runtime
+    * `oops` – Runtime
+    * `opto` – Compiler
+    * `precompiled` – Runtime
+    * `prims` – Runtime, Serviceability
+    * `runtime` – Runtime
+    * `services` – Runtime
+    * `shark` – Compiler
+    * `trace` – Runtime
+    * `utilities` – Runtime
+* `java.base`
+  * Core Libs should almost always be included but LangTools, HotSpot, Security and/or I18n may also be involved.
+  * `classes`
+    * `crypto` – Security
+    * `internal` – HotSpot, Core Libs
+    * `invoke` – Core Libs
+    * `io` – NIO
+    * `lang` – Core Libs
+    * `launcher` – LangTools
+    * `math` – Core Libs
+    * `net` – Net
+    * `nio` – NIO
+    * `reflect` – Core Libs
+    * `security` – Security
+    * `text` – I18n
+    * `time` – Core Libs
+    * `util` – I18n, Core Libs
+  * `conf`
+    * `sdp` – Net
+    * `security` – Security
+  * `legal` –
+  * `lib/security` – Security
+  * `man`
+    * `java.1` - LangTools
+    * `jfr.1` - Runtime
+    * `keytool.1` - Security
+  * `native`
+    * `common` –
+    * `include` – Runtime, Core Libs
+    * `jspawnhelper` – LangTools
+    * `launcher` – LangTools
+    * `libfdlibm` – Core Libs
+    * `libjava` – Core Libs
+    * `libjimage` – LangTools, Core Libs
+    * `libjli` – LangTools
+    * `libjsig` – HotSpot
+    * `libnet` – Net
+    * `libnio` – NIO
+    * `libosxsecurity` – Security
+    * `libverify` – LangTools
+    * `libzip` – Core Libs
+* `java.compiler` – LangTools
+* `java.datatransfer` – AWT
+* `java.desktop` – Client
+  * Many files in the awt directories are shared between 2D and AWT
+    * See [https://openjdk.java.net/groups/2d/2dawtfiles.html](https://openjdk.java.net/groups/2d/2dawtfiles.html)
+    * And see [https://openjdk.java.net/groups/2d](https://openjdk.java.net/groups/2d)
+  * `color`, `font`, `freetype`, `geom`, `imageio`, `java2d`, `jpeg`, `lcms`, `mlib`, `print`, graphics primitives – 2D
+  * `splashscreen`, `dnd`, `eawt`, `lwawt` – AWT
+  * `im`, input methods – I18n, AWT
+  * `libjsound`, `sound` – Sound
+  * `accessibility`, `laf` – Swing
+* `java.instrument` – Serviceability
+* `java.logging` – Core Libs
+* `java.management` – Serviceability
+* `java.management.rmi` – Serviceability
+* `java.naming` – Core Libs
+* `java.net.http` – Net
+* `java.prefs` – Core Libs
+* `java.rmi` – Core Libs
+* `java.scripting` – LangTools
+* `java.se` – Core Libs
+* `java.security.jgss` – Security
+* `java.security.sasl` – Security
+* `java.smartcardio` – Security
+* `java.sql` – Core Libs
+* `java.sql.rowset` – Core Libs
+* `java.transaction.xa` – Core Libs
+* `java.xml` – Core Libs
+* `java.xml.crypto` – Security
+* `jdk.accessibility` – Swing
+* `jdk.aot` – HotSpot Compiler
+* `jdk.attach` – Serviceability
+* `jdk.charsets` – I18n, Core Libs
+* `jdk.compiler` – LangTools
+* `jdk.crypto.cryptoki` – Security
+* `jdk.crypto.ec` – Security
+* `jdk.crypto.mscapi` – Security
+* `jdk.crypto.ucrypto` – Security
+* `jdk.dynalink` – LangTools
+* `jdk.editpad` – LangTools
+* `jdk.hotspot.agent` – Serviceability
+* `jdk.httpserver` – Net
+* `jdk.incubator.foreign` – LangTools
+* `jdk.incubator.httpclient` – Net
+* `jdk.incubator.jpackage` – Client
+* `jdk.incubator.vector` – HotSpot Compiler
+* `jdk.internal.ed` – LangTools
+* `jdk.internal.jvmstat` – Serviceability
+* `jdk.internal.le` – LangTools
+* `jdk.internal.opt` – LangTools
+* `jdk.internal.vm.ci` – HotSpot Compiler
+* `jdk.internal.vm.compiler` – HotSpot Compiler
+* `jdk.internal.vm.compiler.management` – HotSpot Compiler
+* `jdk.jartool` – LangTools
+* `jdk.javadoc` – LangTools
+* `jdk.jcmd` – Serviceability
+* `jdk.jconsole` – Serviceability
+* `jdk.jdeps` – Core Libs
+* `jdk.jdi` – Serviceability
+* `jdk.jdwp.agent` – Serviceability
+* `jdk.jfr` – JFR
+* `jdk.jlink` – LangTools
+* `jdk.jpackage` – Client
+* `jdk.jshell` – LangTools
+* `jdk.jsobject` – LangTools
+* `jdk.jstatd` – Serviceability
+* `jdk.localedata` – I18n
+* `jdk.management` – Serviceability
+* `jdk.management.agent` – Serviceability
+* `jdk.management.jfr` – Runtime
+* `jdk.naming.dns` – Core Libs
+* `jdk.naming.rmi` – Core Libs
+* `jdk.net` – Net
+* `jdk.nio.mapmode` – NIO
+* `jdk.pack` – LangTools
+* `jdk.rmic` – Core Libs
+* `jdk.scripting.nashorn` – LangTools
+* `jdk.scripting.nashorn.shell` – LangTools
+* `jdk.sctp` – Net
+* `jdk.security.auth` – Security
+* `jdk.security.jgss` – Security
+* `jdk.unsupported` – Core Libs
+* `jdk.unsupported.desktop` – Swing
+* `jdk.xml.dom` – Core Libs
+* `jdk.zipfs` – Core Libs
+* `sample` –
+* `utils` –
+
+::: {.box}
+[To the top](#){.boxheader}
+:::

src/guide/contributing-to-an-open-jdk-project.md

@@ -0,0 +1,77 @@
+# Contributing to an OpenJDK Project
+
+Contributing to OpenJDK can take many forms. Writing code and providing patches is just one of them. A big part of developing a feature or a bugfix is testing and code review. Anything you can do to help out in these areas will be recognized as a contribution. Join the [mailing lists](#mailing-lists) to engage in design discussions and reviews, and download the latest EA builds or project repositories to try out new features and give feedback. If you see some misbehavior, or if you see somebody mention some misbehavior on some internet forum, try to track it down. Good bug reports with reproducible test cases are extremely valuable and make excellent contributions.
+
+Anything you can do to spread the word about Java, new features, and your experiences using the JDK will be helpful for the community and to the OpenJDK developers. Trying out a new feature and reporting your experiences is also a contribution. Whether you find that the new feature improves your application, or if you find some area that needs to be improved, your feedback is valuable to the developers of that feature.
+
+If you have a success story where Java solved your problem, or if you successfully upgraded to a more recent version of the JDK and noticed some improvements, spreading this story through a blog, news article, or some other channel is also a contribution.
+
+If you're in a position to choose what programming language to use in a project, in a tutorial, or in a class, you have the power to enlarge the Java community in a very direct way, and your colleagues or students will get an opportunity to learn one of the most used programming languages in the world.
+
+## I have a patch, what do I do?
+
+::: {.box}
+[Quick Links]{.boxheader}
+
+* [Oracle Contributor Agreement (OCA)](https://www.oracle.com/technical-resources/oracle-contributor-agreement.html)
+* [JDK Bug System (JBS)](https://bugs.openjdk.java.net/)
+* [OpenJDK Project Roles](https://openjdk.java.net/bylaws#project-roles)
+:::
+
+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. The JDK is used for mission critical applications and by millions of developers, the bar to contributing changes is high. Please follow the steps outlined below to make sure your change passes above the bar before creating a PR.
+
+### 1. Sign the OCA
+
+Oracle is the steward of OpenJDK. In order to make your patch available for review you must first sign the [Oracle Contributor Agreement](https://oca.opensource.oracle.com/) (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.
+
+When you sign the OCA, please make sure that you specify your GitHub user name in the `Username` field of the OCA. If you try to create a PR before you have signed the OCA, or if you didn't specify your GitHub user name, you'll get instructions telling you to do so, and the PR won't be published until this is done. OCA registration is a manual process. Please allow for up to several days to have your OCA application processed, even though it's normally processed swiftly. An alphabetical list of all of the assigned OpenJDK usernames may be found on the [OpenJDK people](https://db.openjdk.java.net/people) list.
+
+### 2. Socialize your change
+
+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). Almost all changes, and in particular any API changes, must go this route and have a broad agreement in place before there is any point in presenting code. To understand the criteria by which your patch is going to be judged, please read [_Why is My Change Rejected?_](#why-is-my-change-rejected) below. In short, hidden constraints and assumptions, stability and quality, maintainability, compatibility, and conformance to specifications must be considered before your PR is ready to be submitted. If you don't understand the constraints for acceptance, you might be surprised when your PR is rejected.
+
+### 3. Find a sponsor
+
+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 agree 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 facilitate the integration of your work. The sponsor will perform any number of administrative tasks like JBS updates, additional testing, etc. It's usual for a sponsor to also be a reviewer of a change and thus familiar with it, but it's not a requirement.
+
+### 4. Create a tracking issue in JBS
+
+Many OpenJDK projects require a tracking issue to be filed in the [JDK Bug System (JBS)](https://bugs.openjdk.java.net/) before a change can be pushed. This is the case for instance for the JDK and the JDK-Updates projects. In order to get write access to JBS you need to be an [Author](https://openjdk.java.net/bylaws#author) in an OpenJDK project (see [Becoming an Author](#becoming-an-author)). For your first changes, ask your sponsor to help you create the issue or file the bug through the [Bug Report Tool](https://bugreport.java.com/).
+
+### 5. Get acquainted with local process
+
+Even though we strive to unify how things are done within OpenJDK, different areas and projects in OpenJDK may have slight variations in how they work. Some of these differences are highlighted throughout this guide, some aren't. If you're new to an area, make sure you understand local differences before you proceed. Ask your sponsor who should be your main point of contact through your first developer experience in OpenJDK.
+
+## Why is my change rejected?
+
+::: {.box}
+[Quick Links]{.boxheader}
+
+* [Java Language and Virtual Machine Specifications](https://docs.oracle.com/javase/specs/)
+* [Java API Specification](https://docs.oracle.com/en/java/javase/15/docs/api/index.html)
+* [CSR Process](https://wiki.openjdk.java.net/display/csr/Main)
+:::
+
+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.
+
+* **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's held to a high standard of quality. Changes should include tests where practical, and core tests should pass at all times. The value of the change should outweigh the risk of introducing a bug or performance regression.
+
+* **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. New maintainers must be able to understand how to fix 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](https://docs.oracle.com/javase/specs/), the [Java Virtual Machine Specification](https://docs.oracle.com/javase/specs/), and the [Java API Specification](https://docs.oracle.com/en/java/javase/15/docs/api/index.html) ("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's 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.
+
+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.
+
+::: {.box}
+[To the top](#){.boxheader}
+:::

src/guide/fixing-a-bug.md

@@ -0,0 +1,120 @@
+# Fixing a Bug
+
+This is the list of steps which should be performed when fixing a small bug. Small bugs include typos in code or specification, algorithm improvements for correctness or performance, and code changes required to correctly implement the specification.
+
+> ---
+>
+> Some steps refer to operations which can't be performed directly without the assistance of a [Project Committer](https://openjdk.java.net/bylaws#committer). For example, any changes to the [bug database](https://bugs.openjdk.java.net) fall into this category. Since these steps are required, [Contributors](https://openjdk.java.net/bylaws#contributor) are urged to work with their [Sponsors](https://openjdk.java.net/sponsor/) to complete these tasks.
+>
+> ---
+
+For the purposes of brevity this document will use the term "bug" to refer to both bugs and enhancements unless otherwise noted. Hence "fix for a bug" could also imply "implementation for an enhancement".
+
+#. **Discuss the intended change**
+
+   Send an e-mail to the appropriate development mailing list for the Project that maintains the code. The e-mail should have a subject line of the form:
+
+       6543210: My favorite bug
+
+   where `6543210` is replaced with the actual bug id number or "[NEW BUG]" if the bug id isn't known and `My favorite bug` is replaced with the bug's summary.  The message should describe the intended change, which components may be affected, and any other risks or concerns.
+
+#. **Does a bug id exist for the work?**
+
+   **Yes**
+   :   Continue
+
+   **No**
+   :   Create a bug in an appropriate component/sub-component.
+
+#. **Set the bug status to "Open"**
+
+   This communicates intent to fix the bug to other members of the Project. It also sets the expectation for downstream teams such as SQE and JCK that the bug will be fixed in an upcoming integration.
+
+#. **Does the fix for the bug require a specification change, directly affect an external interface, or otherwise have a compatibility impact?**
+
+   **Yes**
+   :   Submission of a CSR request is required. The CSR must be [approved](#approved) before the bug fix is pushed to a feature release or update release repository. The work may begin concurrently with the CSR review, but may need to be modified in response to CSR feedback.
+
+   **No**
+   :   Continue
+
+#. **Fix the bug**
+
+   Assuming that the development team approves of the intended approach, begin working on the code using the latest source available from the appropriate OpenJDK Project [repository](https://hg.openjdk.java.net).
+
+#. [**Is it possible to write a test to detect the bug?**]
+
+   **Yes**
+   :   For bugs, provide a [jtreg](https://openjdk.java.net/jtreg/) regression test as part of the changeset. For enhancements that directly affect one or more exported interfaces, add an adequate set of jtreg unit tests as part of the changeset. By convention all regression and unit tests should contain a [\@bug tag](https://openjdk.java.net/jtreg/tag-spec.html#INFORMATIONAL_TAGS9) referencing at least one bugid.
+
+   :   An entirely new test (or tests) may not be required. For example, if the bug is an existing regression test failure, then when fixing the bug you should just add the new bug ID to the list of space-delimited bugs in the [\@bug tag](https://openjdk.java.net/jtreg/tag-spec.html#INFORMATIONAL_TAGS) of the failing regression test, even if the test didn't need to be updated.
+
+   **No**
+   :   An explanation for why a test is unnecessary or infeasible is required. Such an explanation is recorded by adding a label, and possibly a comment, to the bug report. The label has the prefix [noreg]{.jbs-label} for regression tests and [nounit]{.jbs-label} for unit tests. The suffix of the label is described in detail in the [JBS Label Dictionary](#noreg)
+
+#. **Is modification of shared Java code needed?**
+
+   **Yes**
+   :   It's often sufficient to build and test on a single platform, but sometimes it's not. Use discretion.
+
+   **No**
+   :   Continue
+
+#. **Is modification of shared C code needed?**
+
+   **Yes**
+   :   Build and test on at least one instance of all three of the supported operating systems (Solaris, Linux, and Windows).
+
+   **No**
+   :   Continue
+
+#. **Is modification of C or Java platform-specific code needed?**
+
+   **Yes**
+   :   Build and test on all relevant platforms.  Code under `src/solaris` builds on Solaris, Linux, and MacOS X despite its name.
+
+   **No**
+   :   Continue
+
+#. **Run relevant regression and unit tests on all relevant platforms**
+
+   These include tests for external interfaces as well as other kinds of tests, e.g., HotSpot tests that use internal verification mechanisms.
+
+#. **Run relevant JCK tests on all relevant platforms**
+
+   Running JCK tests is particularly important if the change may have unexpected side-effects.
+
+#. **Request a review of the changes by sending an e-mail to the development alias**
+
+   A patch can be submitted as described in [Contributing](https://openjdk.java.net/contribute/). Alternatively, a ["webrev"](webrevHelp.html) may be generated and uploaded to the [community code review](https://cr.openjdk.java.net/) server. The complete webrev generation and upload procedure is described at [https://cr.openjdk.java.net](https://cr.openjdk.java.net/).
+
+   Changeset pushes before the [Feature Complete](https://openjdk.java.net/projects/jdk8/milestones#Feature_Complete) require at least one [Reviewer](https://openjdk.java.net/bylaws#reviewer); pushes after the Feature Complete require at least two Reviewers. In either case, the more the merrier. Some teams may require more Reviewers. Check with members of the Project.
+
+   Reviewers should examine not only the code being added or changed but also the relevant unit or regression tests.
+
+   A change may require multiple Reviewers because it affects multiple areas.  Reviewers should be aware that they take full responsibility for the appropriateness and correctness of any changes in their area of expertise.  If something goes wrong (e.g., the build breaks) and the change's author is unavailable, they may be asked to deal with the problem. Potential Reviewers are encouraged to refuse to review code for which they aren't qualified.
+
+#. **Create a changeset**
+
+   Follow the instructions in [Producing a Changeset](#producing-a-changeset).
+
+#. **Update the bug content**
+
+   Bug descriptions and comments should be written in a professional manner.
+
+#. **Push the changeset into the Project's forest**
+
+   Follow the instructions in [Producing a Changeset](#producing-a-changeset). If working with a Sponsor, send the changeset to the development mailing list so that they can handle the final push.
+
+   The push will trigger a update to the bug which will make the following changes:
+
+    * Set the bug's "Status" to "Resolved" and "Resolution to "Fixed".
+    * Set the bug's "Fix Version/s" to an appropriate release.
+    * Set the bug's "Resolved in Build" to "team".
+    * Add a Comment containing a reference to the changeset.
+
+_Congratulations!_ Your changeset will now make its way towards a promoted build. When the changeset becomes part of a promoted build, the bug's "Resolved in Build" will have a value of \"b\[1-9\]\[0-9\]*\" to indicate the build number.
+
+::: {.box}
+[To the top](#){.boxheader}
+:::

src/guide/glossary.md

@@ -0,0 +1,26 @@
+# Glossary
+
+[**provisional**]{#provisional} (in the CSR)
+:   The stage of the CSR process after "DRAFT", and "PROPOSED". At this stage the primary goals are to ensure that the proposed changes are suitable for the release in a general sense.
+
+[**approved**]{#approved} (by the CSR)
+:   The stage of the CSR process after "FINALIZED". The CSR has approved the final version of the request which permits push into the project repository.
+
+[**changeset**]{#changeset}
+:   A collection of changes with respect to the current clone of a repository.
+
+[**forest**]{#forest}
+:   A collection of Mercurial repositories which can be managed as a set of nested repositories. The name "Forest" originally came from the Mercurial "Forest Extension" which can be used with some versions of Mercurial, but in general is no longer recommended. The script `common/bin/hgforest.sh` can be used to apply a Mercurial `hg` command to all the repositories in a forest.
+
+[**repository**]{#repository}
+:   A directory tree in the filesystem that Mercurial treats specially. This tree contains the source files and their revision history.
+
+[**trivial**]{#trivial}
+:   A change that is small, well contained, and that makes no semantic changes. Typical examples are fixing obvious typos or renaming a local identifier. A trivial change can also be pushing an already-reviewed change that was missed in an earlier push (e.g., forgot to add a file) or generated changes like a [`git revert`](#backing-out-a-change). It's up to the author of a change to claim that the change is trivial in the RFR, and it's up to the Reviewer whether to approve such a claim. A change is trivial only if the Reviewer agrees that it is. A trivial change doesn't need to wait 24 hours before being pushed, and it only needs one Reviewer, even in areas where stricter rules for pushing normally apply.
+
+[**webrev**]{#webrev}
+:   A tool and its output. In JDK release forests, the script, [`webrev.ksh`](https://hg.openjdk.java.net/code-tools/webrev/raw-file/tip/webrev.ksh), examines a forest or repository to generate a set of web-based views of differences.
+
+::: {.box}
+[To the top](#){.boxheader}
+:::

src/guide/header.md

@@ -0,0 +1 @@
+% OpenJDK Developers' Guide

src/guide/hotspot-development.md

@@ -0,0 +1,37 @@
+# HotSpot Development
+
+## Logging
+
+::: {.box}
+[Quick Links]{.boxheader}
+
+* [JEP 158: Unified JVM Logging](https://openjdk.java.net/jeps/158)
+:::
+
+While developing your fix, your might want your code to output some diagnostic information. You might even want to leave some logging in the code you check in, to facilitate future diagnostics.
+
+The appropriate way to print logging output from HotSpot is through the [Unified Logging Framework (JEP 158)](https://openjdk.java.net/jeps/158). It gives you a lot of nice features and enables common command-line options for all logging. Messages can also be "decorated" with e.g. uptime, level, tags. The JEP contains a thorough description of the feature, but a quick example might look like:
+
+~~~c++
+log_info(gc, marking)("Mark Stack Usage: " SIZE_FORMAT "M", _mark_stack_usage / M);
+~~~
+
+Where 'gc' and 'marking' are tags, and 'info' is the log level. This would be visible if the JVM were run with any of the following flags:
+
+~~~c++
+-Xlog:gc+marking=info
+-Xlog:gc+marking
+-Xlog:gc*
+~~~
+
+The API should be similar to:
+
+~~~c++
+log_<level>(Tag1[,...])(fmtstr, ...)
+~~~
+
+At the time of writing, the different log levels can be found in [src/hotspot/share/logging/log.hpp](https://github.com/openjdk/jdk/blob/master/src/hotspot/share/logging/log.hpp).
+
+::: {.box}
+[To the top](#){.boxheader}
+:::

src/guide/introduction.md

@@ -0,0 +1,11 @@
+# Introduction
+
+Welcome to the OpenJDK Developers' Guide!
+
+The OpenJDK Community is the place to collaborate on open-source implementations of the Java Platform, Standard Edition, and related projects. It was created in November 2006, when initial portions of the JDK source code were published under the GPLv2 license.
+
+In order to work together efficiently, clear directions are sometimes needed to avoid misconceptions and to align developers' views of terminology and process. The OpenJDK Community is a fairly pragmatic place. "Do the right thing" is most often the right course of action. Still, if people do things in the same right way then everyone's work becomes more transparent and easier for others to follow. For this reason most parts of the development process have standard flows that are the recommended ways to do things.
+
+The goal of this guide is to answer questions that developers of the JDK might have around development process, tooling, standards, and so forth. The formal rules and processes are described in other documents, such as [JEP 1](https://openjdk.java.net/jeps/1) for the JDK Enhancement-Proposal & Roadmap Process, and [JEP 3](https://openjdk.java.net/jeps/3) for the JDK Release Process. This guide is meant to be a complement to such documents, with tutorials and examples for how to follow these rules and how to work together with the rest of the OpenJDK Community.
+
+There are many common use cases that aren't detailed in the formal process. This guide suggests how to work in such cases.

src/guide/mailing-lists.md

@@ -0,0 +1,49 @@
+# Mailing Lists
+
+::: {.box}
+[Quick Links]{.boxheader}
+
+* [OpenJDK Mailing Lists Manager](https://mail.openjdk.java.net/mailman/listinfo)
+:::
+
+The mailing lists are the key communications mechanism for all OpenJDK work. All participation in an OpenJDK project starts with joining the relevant mailing list. A subscriber to an OpenJDK mailing list is referred to as a [Participant](https://openjdk.java.net/bylaws#participant) in the [Bylaws](https://openjdk.java.net/bylaws). As a general recommendation we suggest to subscribe to [announce](https://mail.openjdk.java.net/mailman/listinfo/announce), [discuss](https://mail.openjdk.java.net/mailman/listinfo/discuss), and the `-dev` lists covering your explicit area of interest. All OpenJDK mailing lists are found here:
+
+> [`mail.openjdk.java.net`](https://mail.openjdk.java.net/mailman/listinfo)
+
+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 OpenJDK on behalf of your employer, please also list this affiliation. If your GitHub username differs from your real name it's also a good idea to include that to identify yourself and your actions on GitHub.
+
+You must be a member of a list to be able to post to that list. Some lists are moderated to keep the content on topic. Each list has its own archive where you can browse older conversations on the list.
+
+There are a few different types of lists. The list name has two parts to explain what the list is intended for, `<name>-<suffix>`. The name often refers to the project that owns the list or a specific area of interest that the list focuses on. The suffix is explained below. Not all projects or areas have all types of lists described here.
+
+> `-dev`
+> :    Technical discussions around the implementation of the project artifacts. This is also where code reviews happen.
+
+> `-use`
+> :    Technical discussions around the usage of the project artifacts.
+
+> `-discuss`
+> :    General discussions around the project. The special case `discuss(at)openjdk.java.net` is used for general discussions around OpenJDK. Discussions around new project proposals usually happens here.
+
+>  `-changes`
+> :    Changeset notifications from the source code repositories maintained by the project.
+
+> `-announce`
+> :    General project announcements. These lists are tightly moderated and are expected to be low traffic. The special case `announce(at)openjdk.java.net` is used for announcements for OpenJDK.
+
+> `-experts`
+> :    Expert group discussions. The list is restricted; only members of the expert group can subscribe.
+
+> `-observers`
+> :    Open for anyone to subscribe to see what the experts are discussing and potentially to have some dialog with other non-experts. There is no guarantee that an expert is subscribed to the `-observers` list or will see any responses on that list.
+
+> `-comments`
+> :    Used by observers to directly provide feedback/comments to the experts (typically a lead will process the comments list and forward things on to the experts list).
+
+## Changing your email address
+
+If you need to change your registered email address, or if you have any other problems with the mailing lists, please contact [mailman@openjdk.java.net](mailto:mailman@openjdk.java.net).
+
+::: {.box}
+[To the top](#){.boxheader}
+:::

src/guide/release-notes.md

@@ -0,0 +1,125 @@
+# Release Notes
+
+::: {.box}
+[Quick Links]{.boxheader}
+
+* [JDK Release Notes](https://www.oracle.com/java/technologies/javase/jdk-relnotes-index.html)
+* [release-note label description](#release-note)
+* [CommonMark Spec](https://spec.commonmark.org/current/)
+* [dingus](https://spec.commonmark.org/dingus/)
+:::
+
+Release notes for a product such as the JDK are part of the release deliverables providing a way to highlight information about a fix, such as when it may have changed behavior, or when it's decided not to fix something. While what should go into a release note isn't something that can be precisely defined, it should describe changes that are important for a user to take into account when they are upgrading to the specific version. While release notes should not duplicate information in other documents, they can serve to highlight that a change has been made.
+
+Release notes are associated with a JBS issue that has been fixed (or in some cases not been fixed) in a release and are generated with each build of a release. Any note should be considered as an integral part of the fix process, rather than waiting until the end of the release to determine what to write. In OpenJDK, release notes are currently being generated for the JDK and JDK Updates projects.
+
+## Writing a release note
+
+Writing the release note is the responsibility of the engineer who owns the issue. The note should be generated before the fix is reviewed, or in the case of known issues, when it's determined that a fix won't be possible in the release the issue was found in.
+
+When writing a release note, be prepared for rather picky review comments about grammar, typos, and wording. This is for the sake of the Java community as a whole, as the language of the release note sets the tone for many blogs and news articles. For a widely used product like the JDK, the release notes are often copied verbatim (including typos) and published to highlight news in the release. This means that we need to take extra care to make sure the text in the release note is correct and follows a similar style.
+
+The release note itself is written in a [JBS](#jbs---jdk-bug-system) sub-task of the issue that is used to push the change. There are a few steps to follow for the release note to find its way from JBS to the actual release note document.
+
+#. Create a sub-task (More → Create Sub-Task) for the issue that requires a release note - the main issue, that is, the JBS issue that is used to push the original change, **not** for backports or the CSR (if there is one).
+
+#. For the newly created sub-task, follow these steps:
+   * The [Summary]{.jbs-field} should be a one sentence synopsis that is informative (and concise) enough to attract the attention of users, developers, and maintainers who might be impacted by the change. It should succinctly describe what has actually changed, not be the original bug title, nor describe the problem that was being solved. It should read well as a sub-section heading in a document.
+   * Prefix the [Summary]{.jbs-field} with "Release Note:".
+   * Add the [release-note]{.jbs-label} label. This is required for the release note to be included in the release notes.
+   * Add the proper [RN-]{.jbs-label}label if applicable to indicate what section of the release notes it should be included in (see [RN-labels](#rn-labels) below).
+   * Set the [Assignee]{.jbs-field} to the same person who owns the main issue.
+   * Set [Affects Version/s]{.jbs-field} to the release versions for which the release note should be published.
+   * Set the [Fix Version/s]{.jbs-field} to the same value that the main issue - in almost all cases this will be the version of mainline.
+   * Enter the text of the release note in the [Description]{.jbs-field} field using markdown formatting, following the [CommonMark specification](https://spec.commonmark.org/current/). While the markdown won't be rendered in JBS, you can use [dingus](https://spec.commonmark.org/dingus/) to see what the release note will look like. Note that [Github stlye ascii table formatting](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables) is supported but will not display correctly in the dingus page. For more information see [General Conventions for Release Notes](#general-conventions-for-release-notes) below.
+   * While the [Priority]{.jbs-field} of the sub-task is set by default to be the same as the priority of the issue itself, it can be changed to adjust in what order the release note is listed compared to other release notes in the same build or release note section.
+
+#. Have the release note ready to be reviewed at the same time as the code is reviewed. If it's later determined that a release note is necessary, then go back to the same engineers who reviewed the fix to review the release note.  Special care should be taken when writing a release note that will cover changes related to a vulnerability fix in order to avoid describing technical details of how it could have been exploited.
+
+#. When you are done, _Resolve_ the release note sub-task as `Delivered`. Only release notes where the sub-task has been resolved as `Delivered` is considered to be part of the EA/GA release notes. To avoid mixing up the release notes with the code fixes that have gone into a particular release or build, we don't use `Resolved/Fixed`.
+
+If you see an issue you feel should have a release note but you are not the assignee of the bug, then add the label [release-note=yes]{.jbs-label} to the main bug (not on a backport nor a sub-task). This acts as a flag to make sure that the release note is considered. This can be done even with fixes that have been shipped already if it's noticed that there is confusion around the change. If, after discussion, it's decided that a release note isn't required either remove the label, or change it to [release-note=no]{.jbs-label} if it makes sense to have a clear indication that a release note isn't required for the fix. The label [release-note=yes]{.jbs-label} can be removed once the release note sub-task has been created.
+
+For examples of well written release note issues in JBS, see [JDK-8276929](https://bugs.openjdk.java.net/browse/JDK-8276929) or [JDK-8278458](https://bugs.openjdk.java.net/browse/JDK-8278458).
+
+## General Conventions for Release Notes
+
+The following are general practices that should be followed when creating release notes.
+
+* Release notes should be no longer than 2-3 paragraphs.
+* Don't repeat information that will be included in updates to the docs, keep it to a high level summary or key changes.
+* Note that where the changes are more fully documented in the JDK documentation, then refer to that document for details. When covering a change in behavior provide some idea to what can be done if a developer or user encounters problems from the change.
+* Don't include graphics etc. Refer to the main docs if there are more details that need explaining.
+* Don't include your name or affiliation, make sure however, you are the assignee of the release note sub-task.
+* If you have a < in the [Summary]{.jbs-field} then use `&lt;`. For <'s in the [Description]{.jbs-field} surround them by back-ticks.
+
+* Avoid using Latin and abbreviations in the release note.
+  * Use "also known as" instead of "aka"
+  * Use "that is" or "to be specific" instead of "i.e."
+  * Use "for example" instead of "e.g."
+
+* The [Summary]{.jbs-field} should be in title case instead of sentence case.
+  * Example: Decode Error with Tomcat Version 7.x
+
+* The [Description]{.jbs-field} should be standardized to follow this pattern:
+  * Sentence stating the change that was made
+  * Background info/context
+  * Example: A new system property, `jdk.disableLastUsageTracking`, has been introduced to disable JRE last usage tracking for a running VM.
+
+* Special case: JEP release note
+  * [Summary]{.jbs-field} - If the change is an actual JEP, use the JEP title.
+  * [Description]{.jbs-field} - the JEP Summary text have already been heavily reviewed and also approved by the project lead. It should be the first sentence in the release note description. That would be analogous to the "change that was made" sentence in other release note descriptions. The remaining text would be composed of the background info from the JEP.
+  * [Description]{.jbs-field} - The JEP release note description should contain the link to the JEP.
+
+## RN-labels
+
+Unless labeled otherwise it will be assumed that the release note documents a change in behavior (will have likely required a CSR) or other item which should be included in the release notes. If the note covers a more specific type of change, then one of the following labels can be included (notes of a similar type will be listed together).
+
+[[RN-NewFeature]{.jbs-label}]{#RN-NewFeature}
+:   A New Feature or enhancement in the release.
+    The [Summary]{.jbs-field} must be the item/API or new functionality.
+    The [Description]{.jbs-field} must contain the name of the new feature, its intended function, and how a user can utilize it.
+    Example: [JDK-8193026](https://bugs.openjdk.java.net/browse/JDK-8193026)
+
+[[RN-IssueFixed]{.jbs-label}]{#RN-IssueFixed}
+:   A significant issue which has been fixed. This would normally be a regression or an issue which was unknowingly released in a new feature.
+    The [Summary]{.jbs-field} must be a summary of the error that was fixed.
+    The [Description]{.jbs-field} must contain a statement about what was fixed, how the fix effects the user, and any special conditions that a user should be aware of regarding the fix.
+    Example: [JDK-8184172](https://bugs.openjdk.java.net/browse/JDK-8184172)
+
+[[RN-KnownIssue]{.jbs-label}]{#RN-KnownIssue}
+:   An issue that wasn't possible to fix by the time the release was GA'd.
+    The [Summary]{.jbs-field} must be a summary of the error that the user sees.
+    The [Description]{.jbs-field} must contain details about the error, how it effects the user, and workarounds if any exist.
+    Example: [JDK-8191040](https://bugs.openjdk.java.net/browse/JDK-8191040)
+
+[[RN-Removed]{.jbs-label}]{#RN-Removed}
+:   Only for major releases. The release note covers an API, feature, tool etc. which has been removed from the JDK.
+    The [Summary]{.jbs-field} must be of the form "Removal of" Item/API.
+    The [Description]{.jbs-field} must contain the list or name of the removed items/API with (optional) the reason for its removal. Include any special conditions that a user should be aware of regarding the removal.
+    Example: [JDK-8185066](https://bugs.openjdk.java.net/browse/JDK-8185066)
+
+[[RN-Deprecated]{.jbs-label}]{#RN-Deprecated}
+:   Only for major releases. The release notes cover an API, feature, tool etc. that has been marked as deprecated in the release.
+    The [Summary]{.jbs-field} must be of the form "Deprecated" Item/API.
+    The [Description]{.jbs-field} must contain the name of the item that has been deprecated, the reason for its deprecation, and (optional) any special conditions that a user should be aware of regarding the possible future removal.
+    Example: [JDK-8179909](https://bugs.openjdk.java.net/browse/JDK-8179909)
+
+[[RN-Important]{.jbs-label}]{#RN-Important}
+:   Used to indicate that the release note should be highlighted in some fashion, such as listing it at the beginning of the release notes.
+
+[[RN-]{.jbs-label}_(distro)_]{#RN-distro}
+:   Used to indicate that the release note is only relevant for a specific JDK distribution. E.g. [RN-Oracle]{.label}
+
+[[~~RN-Change~~]{.jbs-label}]{#RN-Change}
+:   Deprecated.
+
+## Querying the Release Notes
+
+The Release Notes for a particular release can be found using the JBS query
+
+~~~
+affectedversion = <version> and type = sub-task and labels = release-note
+~~~
+
+where `<version>` is the appropriate release value, e.g. 17.

src/guide/the-jdk-release-process.md

@@ -0,0 +1,67 @@
+# The JDK Release Process
+
+::: {.box}
+[Quick Links]{.boxheader}
+
+* [JEP 3: JDK Release Process](https://openjdk.java.net/jeps/3)
+:::
+
+The JDK project has a well defined release process. [JEP 3](https://openjdk.java.net/jeps/3) describes this process in detail. This section intends to clarify some topics that often cause questions.
+
+## Release cycle
+
+The release cycle starts when development of a new release begins, and ends when that release is delivered to the public. The current release cadence is six months. This means that every six months we start development of a new release, and every six months a new release is delivered. However, this doesn't mean that each release cycle is six months. As described below, the total development time for a release (the release cycle) is actually nine months. Obviously this in turn doesn't mean that all features are developed in nine months. Most features are developed for a much longer time than that, and goes through long time development in other project repositories, and through a series of preview and experimental stages. But any feature that is to be included in a specific release has a specific window of nine months to integrate the code into mainline and fix all the remaining bugs.
+
+It may be tempting to integrate a new feature near the end of a release cycle, to get more time to fix all those last bugs before integration. Please don't. If you are getting close to the end of a release and you still just have one more bug to fix, please defer your feature to the next release. It's only six months out. Not only will this vouch for your new feature to be more stable on release, you will also help keeping the JDK as a whole more stable by allowing others to find and fix bugs in their new code that might come as a result of your changes.
+
+Integrating early in a release is preferable, but all new features can't be integrated at the same time. If many large changes enters the repository at the same time it will be more difficult to determine which change that caused all the new bugs. If you're about to integrate a larger change you must therefore communicate this on the relevant [mailing lists](#mailing-lists) to synchronize with other projects that may also be planning to integrate something soon.
+
+## Milestones and phases
+
+Throughout the release there are a number of milestones and phases that define where in the release cycle we are.
+
+[**The start of a release**]{#release-start}
+:    Since development is always ongoing in the mainline repository ([openjdk/jdk](https://github.com/openjdk/jdk)), the start of a new release can be said to be when the former release is forked from mainline. After the start of the release follows six months of development to implement and integrate all the cool stuff that will go into the next release. After these six months ramp down begins.
+
+[**Ramp Down Phase 1 (RDP1)**]{#rdp1}
+:    The ramp down of a release starts with a fork of the mainline repository. A clone of the entire code base is made and hosted in a separate ramp down repository (e.g. [openjdk/jdk17](https://github.com/openjdk/jdk17)). During the ramp down of a release we focus on bug fixing and stabilization in order to get the JDK ready for release. In RDP1 you may continue to fix P1-P3 product bugs (and some other issues) in the stabilization repo. For detailed information on what can be fixed when, see [JEP 3](https://openjdk.java.net/jeps/3). The start of RDP1 is essentially the deadline for integrating JEPs and enhancements into this particular release.
+
+[**All Tests Run (ATR)**]{#atr}
+:    ATR is not a milestone described in JEP 3, but it's still a concept that might be mentioned in discussions on this topic and is therefore good to know about. ATR (a.k.a. ATR Start) is the start of an approximately six week long test period where all tests in the test plan for the given release is ran. ATR usually starts at the same time as RDP1.
+
+[**Ramp Down Phase 2 (RPD2)**]{#rdp2}
+:    In RDP2 the bar is higher to get changes into the release. For product bugs, only P1:s and P2:s are supposed to be fixed here, and to do so an approval is needed. See the [Fix-Request Process](https://openjdk.java.net/jeps/3#Fix-Request-Process) for details on how to obtain one. All other product bugs should be deferred. Again, see [JEP 3](https://openjdk.java.net/jeps/3) for more details.
+
+[**Release Candidate (RC)**]{#rc}
+:    Towards the end of the release cycle, when there are no more open product bugs targeted to the release, a stable build is selected to be the release candidate. This build will go through additional testing and if no more issues are found it will be the build released. If new bugs are found these are investigated and hopefully fixed, and a new build becomes the release candidate. The RC phase has a few milestones with a deadline for finding a candidate build, and another for making sure the build is ready to go live.
+
+[**General Availability (GA)**]{#ga}
+:    This is the end of the release cycle. The last release candidate build is made available to the public.
+
+### Deferring P1 and P2 bugs
+
+Even though there's nothing explicitly written in the process about deferring P1 and P2 bugs during the initial development phase, the assumption is that these aren't deferred unless time runs out at the end of the release cycle.
+
+Please note that the priority of a bug doesn't change just because you want to get your fix in late in the release, or if you want to be able to defer it. The priority is based on the severity of the bug and if it was deemed to be a P2 before, you better have a really good explanation to why that conveniently has changed by the end of the release. Being hard to fix is **not** a reason to lower the priority of a bug.
+
+## Forward ports
+
+During the rampdown of a release there are two repositories in play, the stabilization fork for the outgoing release, and the mainline repository where the next release is being developed. Any bugfix going into the stabilization fork is likely to be desired in mainline as well. As a developer you should push your fix to the stabilization fork **only**, even if you intend for it to go to both repositories. Your fix will be forward ported to mainline.
+
+_All_ fixes that are pushed to the stabilization fork are forward ported to mainline. If you have a fix that is only intended for the stabilization fork you will have to **manually** back it out from mainline once it has been forward ported. In order to remember to do this you should file a backout isue in JBS before pushing your change to the stabilization fork. E.g., To push JDK-xxx to the stabilization fork but not to mainline, you need to file an issue, JDK-yyy, in JBS to back out the fix after it has been merged into mainline. Make sure the two JBS issues (JDK-xxx and JDK-yyy) are related so that it's easy to find one from the other.
+
+To clarify, as soon as you know that there is a fix that needs to go into the stabilization fork but not mainline, you should do the following:
+
+* File a bug, JDK-yyy, to cover the backout work
+* [Link]{.jbs-field} JDK-yyy to JDK-xxx using a `relates to` link
+* Set JDK-yyy's [Fix Version/s]{.jbs-field} to the release currently being developed in mainline
+* Add a comment describing the situation
+* Set the [Priority]{.jbs-field} to be relatively high (e.g., P3)
+
+Then, you have to wait until the JDK-xxx fix is forward ported to mainline before actually fixing JDK-yyy. Making these settings in JDK-yyy will help ensure that it won't be missed.
+
+There are also examples in JBS where JDK-yyy has been created as a sub-task of JDK-xxx. This works, but isn't recommended since JDK-yyy stands a higher risk of being missed when it's not of type *Bug* but rather a *sub-task* of an already closed issue. Also see [Backing out a change](#backing-out-a-change) for reference.
+
+::: {.box}
+[To the top](#){.boxheader}
+:::

src/guide/working-with-pull-requests.md

@@ -0,0 +1,83 @@
+# Working With Pull Requests
+
+::: {.box}
+[Quick Links]{.boxheader}
+
+* [Skara documentation on PR commands](https://wiki.openjdk.java.net/display/SKARA/Pull+Request+Commands)
+:::
+
+Once you have made a change that you want to integrate into an OpenJDK code base you need to create a _Pull Request_ (PR) on GitHub. This guide assumes that you have previous experience from using git and GitHub and won't go into details of how those work. Still, the aim is of course to provide a useful guide, so [send an email](#about-this-guide) if more details are needed.
+
+## Rebase before creating the PR
+
+It's likely that other people have pushed changes to the code base since you created your branch. Make sure to pull the latest changes and rebase your fix on top of that before creating your PR. This is a courtesy issue. Your reviewers shouldn't have to read your patch on top of old code that has since changed. This is hopefully obvious in cases where the upstream code has gone through cleanups or refactorings, and your patch may need similar cleanups in order to even compile. But even in cases where only smaller changes have been done, the reviewers shouldn't have to react to issues like "that line of code was moved last week, why is it back there?".
+
+~~~
+git rebase master
+~~~
+
+After the PR has been published, rebasing, force-pushing, and similar actions are strongly discouraged. Such actions will disrupt the workflow for reviewers who fetch the PR branch. Pushing new changes is fine (and even merging if necessary) for a PR under review. Incremental diffs and other tools will help your reviewers see what you have changed. In the end, all commits will be squashed into a single commit automatically, so there're actually no drawbacks whatsoever to making commits to a PR branch during review.
+
+## Final check before creating the PR
+
+Creating the PR is essentially the same as asking a large group of people to start reviewing your change. Before doing that, you want to make sure your change is done in every detail you have the power to control. These are a few of the things you should think about in order to avoid wasting people's time on an unfinished change. (You may think that some of these are too obvious to even mention, but all of them are things that in the past have caused actual failures that broke the JDK for **all** developers out there.)
+
+* Is the copyright statement at the top of each modified source file correct?
+
+* Did you run all relevant tests on the final version of the change? (Yes, I mean final! If you only knew how many times people _only changed a comment_ and caused a build failure.)
+
+* Did you `git add` all new files?
+
+* Did you add regression tests for your change?
+
+* Did you run those new regression tests?
+
+If you are unsure of any of these things but still want to go ahead and create the PR, **don't!**
+
+If you have an actual reason to create a PR before the change is all done, make sure to create it in `DRAFT` mode. The bot won't add the `rfr` label or send emails as long as the PR is in `DRAFT` mode.
+
+## Life of a PR
+
+#. **Make sure the PR is reviewable**
+
+   There are changes that span across several areas, for example wide spread cleanups or the introduction of a new langauge feature. Accordingly, the number of lines of code touched can be quite large, which makes it harder to review the entire PR. In such cases, it may make sense to split the change into several PRs, most commonly by grouping them by module or area.
+
+#. **Set a correctly formatted title**
+
+   The title of the PR should be of the form "`nnnnnnn: Title of JBS issue`" where `nnnnnnn` is the JBS issue id of the main JBS issue that is being fixed, and the `Title of JBS issue` is the exact title of the issue as written in JBS. In fact, the title can be set to _only_ the JBS issue id (`nnnnnnn`) in which case the bot will fetch the title from JBS automatically. If you are creating a backport PR, see [Using the Skara tooling to help with backports](#using-the-skara-tooling-to-help-with-backports) for more details on the title requirements.
+
+#. **Write a useful description**
+
+   The description of the PR should state what problem is being solved and shortly describe how it's solved. Reviewers and other interested readers are referred to the text in the JBS issue for details, but the description should be enough to give an overview. This assumes there's useful information in the JBS issue, like an evaluation etc. If not, add it.
+
+   Remember that the description is included in many emails sent to lists with many receivers, so a too long description can cause a lot of noise, while of course a too short description won't give the reader enough information to perform the review. If you have a lot of information you wish to add to your PR, like performance evaluations, you can put that in a separate comment in the PR.
+
+#. **Finish the change before publishing it**
+
+   Each update to a published PR will result in emails being sent to all relevant lists. This is per design and it's how we want it to be, but it also mean that if you publish a PR before you have gone through the final check mentioned above, and later find that a few more updates are necessary, a lot of people will get a lot of emails.
+
+#. **Make sure all relevant groups are included**
+
+   The bot will make an attempt to include the groups that need to review your change based on the location of the source code you have changed. There may be aspects of your change that are relevant to other groups as well, and the mapping from source to groups isn't always perfect, so make sure all relevant groups have been included, and add new labels using [`/label`](https://wiki.openjdk.java.net/display/SKARA/Pull+Request+Commands#PullRequestCommands-/label) if needed.
+
+#. **Allow enough time for review**
+
+   In general all PRs should be open for at least 24 hours to allow for reviewers in all time zones to get a chance to see it. It may actually happen that even 24 hours isn't enough. Take into account weekends, holidays, and vacation times throughout the world and you'll realize that a change that requires more than just a trivial review may have to be open for a while. In some areas [trivial](#trivial) changes are allowed to be pushed without the 24 hour delay. Ask your reviewers if you think this applies to your change.
+
+   At least one reviewer should be knowledgeable in the area being changed. Some areas (e.g. client and hotspot) require two reviewers in most cases, so be sure to read the relevant OpenJDK group pages for advice or ask your sponsor.
+
+#. **Updating the PR**
+
+   You may need to change the code in response to review comments. To do this, simply commit new changes and push them onto the PR branch. The PR will be updated automatically. Multiple commits to the branch will be squashed into a single commit when the PR is eventually integrated.
+
+   If the set of files in the PR has changed, this may affect the groups that need to review the PR. Make sure to adjust the PR labels accordingly.
+
+#. **Merge the latest changes**
+
+   If your PR is out for review for a longer time it's a good habit to pull from the target repository regularly to keep the change up to date. This will make it easier to review the change and it will help you find issues caused by other changes sooner. Typically this involves fetching changes from the master branch of the main JDK repo, merging them into your local branch, resolving conflicts if necessary, and then pushing these changes to the PR branch. Pushing additional commits and merges into the PR branch is fine; they will be squashed into a single commit when the PR is integrated. Avoid rebasing changes, and prefer merging instead.
+
+   If there are upstream changes that might affect your change, it's likely a good idea to rerun relevant testing as well. The GHA testing that's done automatically by GitHub should only be seen as a smoke test that finds the most severe problems with your change. It's highly unlikely that it will test your actual change in any greater detail - or even at all execute the code that you have changed in most cases.
+
+#. **Integrate your change**
+
+   When you have the required reviews and have made sure all relevant areas have had a chance to look at your change, integrate by entering the command [`/integrate`](https://wiki.openjdk.java.net/display/SKARA/Pull+Request+Commands#PullRequestCommands-/integrate) in a comment on the PR. If you are not yet a Committer in the project, ask your sponsor to enter the command [`/sponsor`](https://wiki.openjdk.java.net/display/SKARA/Pull+Request+Commands#PullRequestCommands-/sponsor) in the PR as well in order for your change to be allowed to be integrated.

src/toc.conf

@@ -0,0 +1,19 @@
+header.md
+introduction.md
+contributing-to-an-open-jdk-project.md
+mailing-lists.md
+code-conventions.md
+jbs-jdk-bug-system.md
+fixing-a-bug.md
+cloning-the-jdk.md
+building-the-jdk.md
+testing-the-jdk.md
+working-with-pull-requests.md
+backporting.md
+release-notes.md
+hotspot-development.md
+working-with-the-legacy-mercurial-servers.md
+the-jdk-release-process.md
+code-owners.md
+about-this-guide.md
+glossary.md