diff --git a/README.md b/README.md
index a8ada4c..1ecd280 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,29 @@ The target audience for this document is anyone in the OpenJDK Community who aim
To engage in the development of the Developers' Guide itself, create a private fork and join the dedicated [guide-dev mail list](https://mail.openjdk.java.net/mailman/listinfo/guide-dev).
+### Language in the Developers' Guide
+
+The OpenJDK Developers' Guide is written in American English. The Guide is meant to be an informal document. This is reflected in the language used. For instance, contractions are commonly used.
+
+### Keywords and links
+
+All terms defined in the OpenJDK Bylaws are considered keywords, and should be capitalized. Company and organization names are also considered keywords and follow the same rules. A keyword should be linked to the definition of that term if the keyword is referring to the defined term. Additional words that build a noun phrase should be included in the link.
+
+E.g. The word **Project** is defined in the Bylaws, therefore when writing about OpenJDK Projects there should be a link and a capital **P**. However when writing about other projects no link is required and the case of **p** follow normal grammar rules.
+
+To clarify further, a few examples:
+
+* A [Project](https://openjdk.org/bylaws#project) may produce code. --- The word "Project" refers to an OpenJDK Project as defined in the Bylaws.
+* Y is an [OpenJDK Project](https://openjdk.org/bylaws#project). --- "OpenJDK Project" is a noun phrase and all of it should be included in the link.
+* The Project repository contains code. --- Here "Project repository" refers to the code repository, not the Project, but the Project is still an OpenJDK Project, so it's capitalized but has no link.
+* A [GitHub](https://github.com) project is a different thing. --- Not an OpenJDK Project, however GitHub is a keyword and has is therefore correctly capitalized and has it's own link. If we were writing about a specific GitHub project then a link to that project would be appropriate.
+
+Section headers do not contain links since this mess with our ability to link to said sections.
+
+### CSS formats
+
+There are styles defined in the file `src/guidestyle.css`. These styles should be used exactly for what they are intended for. No more, no less. Always use the correct style when writing words covered by these styles, never use the styles for anything else. The comments in `guidestyle.css` should be obvious enough to understand what the style should be used for.
+
## Building the Developers' Guide
The project comes with a `Makefile`. Simply type `make` to generate HTML files from the source Markdown. The build requires the tools `pandoc`, `iconv`, and `perl` and assumes a POSIX environment. We recommend using at least pandoc 2.0.
diff --git a/src/guide/about-this-guide.md b/src/guide/about-this-guide.md
index c97b0f5..7127e9f 100644
--- a/src/guide/about-this-guide.md
+++ b/src/guide/about-this-guide.md
@@ -1,6 +1,6 @@
# About This Guide
-This guide is being maintained through the [OpenJDK Developers' Guide Project](https://openjdk.org/census#guide). The [source repository](https://github.com/openjdk/guide) is available at GitHub. The revision hash at the bottom of this page refers to the last published commit.
+This guide is being maintained through the [OpenJDK Developers' Guide Project](https://openjdk.org/census#guide). The source repository is available at [GitHub](https://github.com/openjdk/guide). The revision hash at the bottom of this page refers to the last published commit.
Comments and questions may be sent to [guide-dev@openjdk.org](mailto:guide-dev@openjdk.org). Please let us know if there's anything in the guide that isn't clear.
diff --git a/src/guide/cloning-the-jdk.md b/src/guide/cloning-the-jdk.md
index 3ee2d89..29bfbe9 100644
--- a/src/guide/cloning-the-jdk.md
+++ b/src/guide/cloning-the-jdk.md
@@ -11,13 +11,13 @@ After the initial release of the JDK source code into OpenJDK in 2007 the OpenJD
$ 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.
+`openjdk/jdk` is the mainline JDK development repository where the next major release of the JDK is being developed. Other [Projects](https://openjdk.org/bylaws#project) have their own repositories on [GitHub](https://github.com/openjdk).
::: {.note}
-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] to determine the appropriate repository, development conventions, and helpful tools.
+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](https://github.com/openjdk) since other source distributions may contain older code or code which differs due to licensing. Consult the Project's documentation or [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.
+If you intend to contribute patches, you should first *fork* the repository on [GitHub](https://github.com) and clone your own *personal fork* as shown below. To fork a [Project](https://openjdk.org/bylaws#project) on [GitHub](https://github.com), 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:
@@ -35,13 +35,13 @@ graph TD
~~~
:::
-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.
+Pushes to your personal fork can be made either using HTTPS or SSH. These examples assume you have an SSH key installed on [GitHub](https://github.com). 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.
+In the example above Duke cloned his personal fork of the JDK mainline repository using SSH. You should of course use your own [GitHub](https://github.com) 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](https://github.com), there will be a message saying that you just pushed a change and asking if you want to create a PR.
## Working with git branches
@@ -86,7 +86,7 @@ For security reasons you should always create new keys and use different keys wi
| .=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.
+`~/.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](https://github.com). 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"
diff --git a/src/guide/contributing-to-an-open-jdk-project.md b/src/guide/contributing-to-an-open-jdk-project.md
index 9069a30..58acfd1 100644
--- a/src/guide/contributing-to-an-open-jdk-project.md
+++ b/src/guide/contributing-to-an-open-jdk-project.md
@@ -1,6 +1,6 @@
# 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] 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.
+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] 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.
@@ -14,23 +14,23 @@ Every change to JDK code carries a risk of changes in behavior which may adverse
One question to ask yourself is: **What problem are you trying to solve?**
-The important thing here is to understand the problem itself, independent of any solution (and independently of the solution that currently happens to be in the PR). A number of other questions and lines of thought emanate from thinking about the problem. For example: is this the right problem to solve? Does solving this problem create worse problems elsewhere; that is, is there a net benefit? Does this problem need to be solved in the JDK, or can and should it be solved elsewhere (e.g., in tooling)?
+The important thing here is to understand the problem itself, independent of any solution (and independently of the solution that currently happens to be in your change). A number of other questions and lines of thought emanate from thinking about the problem. For example: is this the right problem to solve? Does solving this problem create worse problems elsewhere; that is, is there a net benefit? Does this problem need to be solved in the JDK, or can and should it be solved elsewhere (e.g., in tooling)?
The next question you need to answer before making any change is: **What is the main intention of your change?**
Depending on your answer to that question you will need to consider one or more of the following paragraphs.
-* **Correctness** If your change improves program correctness, that's important. And to broaden this, fixing of all kinds of bugs that really make things better for applications in ways they can detect is important.
+* **Correctness** -- If your change improves program correctness, that's important. And to broaden this, fixing of all kinds of bugs that really make things better for applications in ways they can detect is important.
-* **Robustness** Updating code to use a newer platform API can be a good change. Moving away from APIs that are being deprecated or that are no longer maintained is likely desired. Do note though that supposedly equivalent APIs may not be the drop in replacement you think they are. You'll need to prove that the code has the same behavior after the change through extensive testing.
+* **Robustness** -- Updating code to use a newer platform API can be a good change. Moving away from APIs that are being deprecated or that are no longer maintained is likely desired. Do note though that supposedly equivalent APIs may not be the drop in replacement you think they are. You'll need to prove that the code has the same behavior after the change through extensive testing.
-* **Security** If you intend to increase the overall security of the platform, changes following secure coding practices and using appropriate platform APIs for that are usually welcome. The exception might be if it's a potentially destabilizing change in code where there's only a theoretical problem. Please note: If you think you found a real security bug that might compromise the platform you should follow the process [here](https://openjdk.org/groups/vulnerability/report).
+* **Security** -- If you intend to increase the overall security of the platform, changes following secure coding practices and using appropriate platform APIs for that are usually welcome. The exception might be if it's a potentially destabilizing change in code where there's only a theoretical problem. **Please note**: If you think you found a real security bug that might compromise the platform you should follow the process [here](https://openjdk.org/groups/vulnerability/report).
-* **Refactoring / Cleanup** Making code easier to understand or reducing code size may be a good change in areas that are under active development. Stable code however isn't a good candidate for refactoring regardless of what the code looks like. The OpenJDK has evolved over many years and some parts have been stable for decades. If there's no immediate need to work on the code for other reasons, then what will a cleanup actually achieve? One specific area where refactoring and cleanups are explicitly discouraged is in third-party code.
+* **Refactoring / Cleanup** -- Making code easier to understand or reducing code size may be a good change in areas that are under active development. Stable code however isn't a good candidate for refactoring regardless of what the code looks like. The OpenJDK has evolved over many years and some parts have been stable for decades. If there's no immediate need to work on the code for other reasons, then what will a cleanup actually achieve? One specific area where refactoring and cleanups are explicitly discouraged is in third-party code.
-* **Performance** Can you demonstrate a user perceptible change? If you can't measure the change, or a user can't notice the change, or the change only improves code that is used infrequently, then maybe it isn't worth it. Do you have benchmarks to back up your claims? Do you understand the results? Performance testing is complex and often there are many factors unrelated to your change that affects the numbers. What's the tradeoff? The performance improvements that just make everything better do exist, but they are extremely rare. Most often the code gets more complex, or you speed up one case but slow down another. Are you making the right tradeoff?
+* **Performance** -- Can you demonstrate a user perceptible change? If you can't measure the change, or a user can't notice the change, or the change only improves code that is used infrequently, then maybe it isn't worth it. Do you have benchmarks to back up your claims? Do you understand the results? Performance testing is complex and often there are many factors unrelated to your change that affects the numbers. What's the tradeoff? The performance improvements that just make everything better do exist, but they are extremely rare. Most often the code gets more complex, or you speed up one case but slow down another. Are you making the right tradeoff?
-* **Modernizing** Changing code purely for the sake of using a new language feature isn't usually a good change. Be a subject matter expert, not just a language expert. Writing code in "a better way" is not guaranteed to be safe. A change of behavior is always possible and unless you understand the code you are changing at more than the core language/API level, and have looked into appropriate tests and can speak to the risks, then you should first find a subject matter expert to discuss it with. Keep in mind that the OpenJDK code is developed by a large community. If a new language feature is introduced, all developers working in that code must learn this new feature and understand the implications of using it.
+* **Modernizing** -- Changing code purely for the sake of using a new language feature isn't usually a good change. Be a subject matter expert, not just a language expert. Writing code in "a better way" is not guaranteed to be safe. A change of behavior is always possible and unless you understand the code you are changing at more than the core language/API level, and have looked into appropriate tests and can speak to the risks, then you should first find a subject matter expert to discuss it with. Keep in mind that the OpenJDK code is developed by a large community. If a new language feature is introduced, all developers working in that code must learn this new feature and understand the implications of using it.
## I have a patch, what do I do?
@@ -44,11 +44,11 @@ Depending on your answer to that question you will need to consider one or more
* [OpenJDK Project Roles](https://openjdk.org/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.
+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](https://openjdk.org/bylaws#project) 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
-Like many other open-source communities, the OpenJDK Community requires Contributors to jointly assign their copyright on contributed code. Oracle is the steward of OpenJDK and if you haven't yet signed the [Oracle Contributor Agreement](https://oca.opensource.oracle.com/) (OCA), and are not covered by a company-level agreement, then please do so. This is required in order to make your patch available for review. The OCA 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. If you don't know if your organization has signed the OCA you can check the [OCA Signatories List][https://oca.opensource.oracle.com/?ojr=contrib-list], or ask your legal advisor.
+Like many other open-source communities, the OpenJDK Community requires Contributors to jointly assign their copyright on contributed code. [Oracle](https://www.oracle.com) is the steward of OpenJDK and if you haven't yet signed the [Oracle Contributor Agreement](https://oca.opensource.oracle.com/) (OCA), and are not covered by a company-level agreement, then please do so. This is required in order to make your patch available for review. The OCA gives [Oracle](https://www.oracle.com) and you as a Contributor joint copyright interests in the code. You will retain your copyright while also granting those rights to [Oracle](https://www.oracle.com). If you don't know if your organization has signed the OCA you can check the [OCA Signatories List][https://oca.opensource.oracle.com/?ojr=contrib-list], or ask your legal advisor.
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.
@@ -64,11 +64,11 @@ Socializing your change on the mailing lists also prevents the surprise that wou
### 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.org/) before a change can be pushed. This is the case for instance for the JDK and the JDK Updates projects. In order to obtain write access to JBS you need to be an [Author](https://openjdk.org/bylaws#author) in an OpenJDK project (see [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/).
+Many [OpenJDK Projects](https://openjdk.org/bylaws#project) require a tracking issue to be filed in the [JDK Bug System (JBS)](https://bugs.openjdk.org/) before a change can be pushed. This is the case for instance for the JDK and the JDK Updates Projects. In order to obtain write access to JBS you need to be an [Author](https://openjdk.org/bylaws#author) in an [OpenJDK Project](https://openjdk.org/bylaws#project) (see [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.
+Even though we strive to unify how things are done within OpenJDK, different areas and [Projects](https://openjdk.org/bylaws#project) 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?
@@ -80,23 +80,23 @@ Even though we strive to unify how things are done within OpenJDK, different are
* [CSR Process](https://wiki.openjdk.org/display/csr/Main)
:::
-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. The goal is not to take in the maximum number of contributions possible, but rather to accept only the highest-quality contributions. The JDK is used daily by millions of people and thousands of businesses, often in mission-critical applications, and so every change must be scrutinized in detail. There are many reasons for this.
+Just about every Java developer out there has an idea or two for how to enhance something. And 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. The goal is not to take in the maximum number of contributions possible, but rather to accept only the highest-quality contributions. The JDK is used daily by millions of people and thousands of businesses, often in mission-critical applications, and so every change must be scrutinized in detail. 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.
+* **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.
+* **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.
+* **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.
+* **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.
+* **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.
+* **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.org/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.
+* **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.org/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.
+* **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.
diff --git a/src/guide/glossary.md b/src/guide/glossary.md
index fd5ce7a..3f3f81c 100644
--- a/src/guide/glossary.md
+++ b/src/guide/glossary.md
@@ -4,13 +4,13 @@
: 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.
+: 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.
[**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.
+: 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](https://openjdk.org/bylaws#reviewer) whether to approve such a claim. A change is trivial only if the [Reviewer](https://openjdk.org/bylaws#reviewer) agrees that it is. A trivial change doesn't need to wait 24 hours before being pushed, and it only needs one [Reviewer](https://openjdk.org/bylaws#reviewer), even in areas where stricter rules for pushing normally apply.
::: {.box}
[To the top](#){.boxheader}
diff --git a/src/guide/hotspot-development.md b/src/guide/hotspot-development.md
index b7e873e..8ee84f9 100644
--- a/src/guide/hotspot-development.md
+++ b/src/guide/hotspot-development.md
@@ -2,7 +2,7 @@
See [Working With Pull Requests] for generic guidance and requirements around pushing changes. For the HotSpot codebase there are a few additional requirements:
-* Your change must have been approved by two reviewers out of which at least one is also a Reviewer
+* Your change must have been approved by two reviewers out of which at least one is also a [Reviewer](https://openjdk.org/bylaws#reviewer)
* Your change must have passed through HotSpot tier 1 testing with zero failures (See tier1 definition in `test/hotspot/jtreg/TEST.groups`.)
## Logging
diff --git a/src/guide/introduction.md b/src/guide/introduction.md
index 9812ade..537ad37 100644
--- a/src/guide/introduction.md
+++ b/src/guide/introduction.md
@@ -2,7 +2,7 @@
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.
+The OpenJDK Community is the place to collaborate on open-source implementations of the Java Platform, Standard Edition, and related [Projects](https://openjdk.org/bylaws#project). 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.
@@ -15,49 +15,49 @@ There are many common use cases that aren't detailed in the formal process. This
::: {.box}
[Quick Links]{.boxheader}
-* [OpenJDK Groups](https://openjdk.org/groups/)
-* [OpenJDK Projects](https://openjdk.org/projects/)
+* [OpenJDK Groups](https://openjdk.org/bylaws#group)
+* [OpenJDK Projects](https://openjdk.org/bylaws#project)
* [OpenJDK General Roles (Participant, Contributor, Member)](https://openjdk.org/bylaws#general-roles)
* [OpenJDK Project Roles (Author, Committer, Reviewer)](https://openjdk.org/bylaws#project-roles)
:::
-OpenJDK consists of a number of [Groups](https://openjdk.org/groups/). Members of a group collaborate on an area of mutual interest. The right hand side bar on the [OpenJDK website](https://openjdk.org/) has a list of all groups in OpenJDK. If you're interested in a specific area, this is where you would start your OpenJDK experience. Look at the group's information and wiki pages, and see what projects they sponsor on the [Census page](https://openjdk.org/census). The [Census](https://openjdk.org/census) shows the structure of the OpenJDK Community.
+OpenJDK consists of a number of [Groups](https://openjdk.org/bylaws#group). Members of a [Group](https://openjdk.org/bylaws#group) collaborate on an area of mutual interest. The right hand side bar on the [OpenJDK website](https://openjdk.org/) has a list of all [Groups](https://openjdk.org/bylaws#group) in OpenJDK. If you're interested in a specific area, this is where you would start your OpenJDK experience. Look at the [Group's](https://openjdk.org/bylaws#group) information and wiki pages, and see what [Projects](https://openjdk.org/bylaws#project) they sponsor on the [Census page](https://openjdk.org/census). The [Census](https://openjdk.org/census) shows the structure of the OpenJDK Community.
-[Projects](https://openjdk.org/projects/) are where the coding and much of the other work is done in OpenJDK. There are many different projects, some produce shippable artifacts, like the [JDK Project](https://openjdk.org/projects/jdk/), some produce tools to be used by developers of these artifacts, like the [Code Tools Project](https://openjdk.org/projects/code-tools/) or [Project Skara](https://openjdk.org/projects/skara/), and some produce documentation, like the [Developers' Guide Project](https://openjdk.org/projects/guide/). Many projects designs and develops new features for the Java language or the JVM, but there are also less code centric projects like the [Duke Project](https://openjdk.org/projects/duke/) which collects images of the Java mascot, Duke.
+[Projects](https://openjdk.org/bylaws#project) are where the coding and much of the other work is done in OpenJDK. There are many different [Projects](https://openjdk.org/bylaws#project), some produce shippable artifacts, like the [JDK Project](https://openjdk.org/projects/jdk/), some produce tools to be used by developers of these artifacts, like the [Code Tools Project](https://openjdk.org/projects/code-tools/) or [Project Skara](https://openjdk.org/projects/skara/), and some produce documentation, like the [Developers' Guide Project](https://openjdk.org/projects/guide/). Many [Projects](https://openjdk.org/bylaws#project) designs and develops new features for the Java language or the JVM, but there are also less code centric ones like the [Duke Project](https://openjdk.org/projects/duke/) which collects images of the Java mascot, Duke.
## Author, Committer, Reviewer
-OpenJDK has a few different roles that determine who has the right to do what in the different projects. These roles are defined in the [OpenJDK Bylaws](https://openjdk.org/bylaws#project-roles). The roles are earned based on experience and knowledge within each project.
+OpenJDK has a few different roles that determine who has the right to do what in the different [Projects](https://openjdk.org/bylaws#project). These roles are defined in the [OpenJDK Bylaws](https://openjdk.org/bylaws#project-roles). The roles are earned based on experience and knowledge within each [Project](https://openjdk.org/bylaws#project).
-A Contributor can have different roles in different projects. When you're new to a project you don't yet have a formal role in that specific project, even though you might have earned roles in other OpenJDK projects or have been recognized as a [Contributor](https://openjdk.org/bylaws#contributor) or a [Member](https://openjdk.org/bylaws#openjdk-member) of OpenJDK. By contributing high-quality content you'll soon be eligible for [OpenJDK roles](https://openjdk.org/bylaws#project-roles) in the project. First [Author](https://openjdk.org/bylaws#author), then [Committer](https://openjdk.org/bylaws#committer), and finally [Reviewer](https://openjdk.org/bylaws#reviewer) if you stay active and earn the trust of the community. Trust is an important part of earning these roles. There's a [rough guideline](https://openjdk.org/projects/) saying that to become a [Committer](https://openjdk.org/bylaws#committer) you should have contributed 8 significant changes, and to become a [Reviewer](https://openjdk.org/bylaws#reviewer) you should have contributed 32 significant changes. In reality it's not as easy as "just" contributing code. You need to build a track record of good decisions and sound judgment and show that you know what differentiates a good change from a not so good one. It's not only correctness of the code that matters, it's also the appropriateness. In the end the trust you've earned is put to the test through a vote.
+A [Contributor](https://openjdk.org/bylaws#contributor) can have different roles in different [Projects](https://openjdk.org/bylaws#project). When you're new to a [Project](https://openjdk.org/bylaws#project) you don't yet have a formal role in that specific [Project](https://openjdk.org/bylaws#project), even though you might have earned roles in other [OpenJDK Projects](https://openjdk.org/bylaws#project) or have been recognized as a [Contributor](https://openjdk.org/bylaws#contributor) or a [Member](https://openjdk.org/bylaws#openjdk-member) of OpenJDK. By contributing high-quality content you'll soon be eligible for [OpenJDK roles](https://openjdk.org/bylaws#project-roles) in the [Project](https://openjdk.org/bylaws#project). First [Author](https://openjdk.org/bylaws#author), then [Committer](https://openjdk.org/bylaws#committer), and finally [Reviewer](https://openjdk.org/bylaws#reviewer) if you stay active and earn the trust of the community. Trust is an important part of earning these roles. There's a [rough guideline](https://openjdk.org/projects/) saying that to become a [Committer](https://openjdk.org/bylaws#committer) you should have contributed 8 significant changes, and to become a [Reviewer](https://openjdk.org/bylaws#reviewer) you should have contributed 32 significant changes. In reality it's not as easy as "just" contributing code. You need to build a track record of good decisions and sound judgment and show that you know what differentiates a good change from a not so good one. It's not only correctness of the code that matters, it's also the appropriateness. In the end the trust you've earned is put to the test through a vote.
-Note that when a new project is created an initial set of members can be brought in at different levels without a vote.
+Note that when a new [Project](https://openjdk.org/bylaws#project) is created an initial set of members can be brought in at different levels without a vote.
### Becoming an Author
-Becoming an [Author](https://openjdk.org/bylaws#author) is the first step. To achieve this you need to contribute two changes to the project in which you wish to become an Author. Once your changes are pushed into the code base and has been vetted enough to determine that the changes were indeed good changes you can go ahead and send an email to the project lead of that particular project and ask to be added as an Author. Note that "the project" is not OpenJDK, but rather the specific development project where you did your contributions (e.g. "JDK", "JDK Updates", "Amber", etc). The [OpenJDK Project description](https://openjdk.org/projects/#project-author) has a template for such an email. In short the email should contain your name, the project name, your email address, and GitHub links to your changes. In response to your email you will get a time-limited invite which you should fill out.
+Becoming an [Author](https://openjdk.org/bylaws#author) is the first step. To achieve this you need to contribute two changes to the [Project](https://openjdk.org/bylaws#project) in which you wish to become an [Author](https://openjdk.org/bylaws#author). Once your changes are pushed into the code base and has been vetted enough to determine that the changes were indeed good changes you can go ahead and send an email to the Project lead of that particular [Project](https://openjdk.org/bylaws#project) and ask to be added as an [Author](https://openjdk.org/bylaws#author). Note that "the [Project](https://openjdk.org/bylaws#project)" is not OpenJDK, but rather the specific [development Project](https://openjdk.org/bylaws#project) where you did your contributions (e.g. "JDK", "JDK Updates", "Amber", etc). The [OpenJDK Project description](https://openjdk.org/projects/#project-author) has a template for such an email. In short the email should contain your name, the Project name, your email address, and GitHub links to your changes. In response to your email you will get a time-limited invite which you should fill out.
-To see who the project lead is for your project, see the [OpenJDK Census](https://openjdk.org/census). The Census unfortunately doesn't provide email addresses for people, but assuming you have been active on the project mailing list (since you are applying for Author after all), you should be able to find the lead's email address in your local email archive, or ask your sponsor.
+To see who the Project lead is for your [Project](https://openjdk.org/bylaws#project), see the [OpenJDK Census](https://openjdk.org/census). The [Census](https://openjdk.org/census) unfortunately doesn't provide email addresses for people, but assuming you have been active on the Project mailing list (since you are applying for [Author](https://openjdk.org/bylaws#author) after all), you should be able to find the lead's email address in your local email archive, or ask your [Sponsor](https://openjdk.org/bylaws#sponsor).
-As an Author you will get your OpenJDK user name. Once you have gotten the user name, this should be associated with your GitHub account in order for the bots to be able to identify you on GitHub. See the [Skara documentation](https://wiki.openjdk.org/display/SKARA#Skara-AssociatingyourGitHubaccountandyourOpenJDKusername) for more details on that. Once that's done you can create PRs and get them reviewed, but you will still need a sponsor to approve your change before it can be integrated. You'll also get write access to [JBS](#jbs---jdk-bug-system) and the [OpenJDK wiki](https://wiki.openjdk.org) related to the project in question, and to [cr.openjdk.org](https://cr.openjdk.org) via an SSH key provided at the time you accept your invitation.
+As an [Author](https://openjdk.org/bylaws#author) you will get your OpenJDK user name. Once you have gotten the user name, this should be associated with your GitHub account in order for the bots to be able to identify you on [GitHub](http://www.github.com). See the [Skara documentation](https://wiki.openjdk.org/display/SKARA#Skara-AssociatingyourGitHubaccountandyourOpenJDKusername) for more details on that. Once that's done you can create PRs and get them reviewed, but you'll still need a [Sponsor](https://openjdk.org/bylaws#sponsor) to integrate changes. You'll also get write access to [JBS](#jbs---jdk-bug-system) and the [OpenJDK wiki](https://wiki.openjdk.org) related to the [Project](https://openjdk.org/bylaws#project) in question, and to [cr.openjdk.org](https://cr.openjdk.org) via an SSH key provided at the time you accept your invitation.
-The rules of any particular project may have different guidelines regarding requirements for Authorship at the discretion of the Lead.
+The rules of any particular [Project](https://openjdk.org/bylaws#project) may have different guidelines regarding requirements for Authorship at the discretion of the Lead.
### Becoming a Committer
-To become a [Committer](https://openjdk.org/bylaws#committer) you should show that you intend to actively contribute to the project and that you can produce non-trivial changes that are accepted for inclusion into the project code base. The number eight has been seen as a formal lower limit on the number of changes, but since the changes must be non-trivial, or "significant" as the [OpenJDK Project description](https://openjdk.org/projects/) says, and the definition of significant is subjective, the general recommendation is to wait with a Committer nomination until there's at least 10-12 changes pushed to have some margin for different interpretations of "significant". In practice though, we have seen several examples where the number of significant changes hasn't been the dominating factor in a Committer vote. A Contributor's work in another OpenJDK project may also be relevant for the vote. What the vote should ultimately test is the Contributor's commitment to the OpenJDK project for which the vote applies - is it believed that the person is dedicated and willing to spend time and effort on the project? Is the person believed to be a good citizen of the project? It's always a good idea to seek the advice of a sponsor who can guide you through the process to becoming a Committer - you will need one to run the Committer vote anyway. They will probably also have a better idea of what constitutes a "significant" change.
+To become a [Committer](https://openjdk.org/bylaws#committer) you should show that you intend to actively contribute to the [Project](https://openjdk.org/bylaws#project) and that you can produce non-trivial changes that are accepted for inclusion into the Project code base. The number eight has been seen as a formal lower limit on the number of changes, but since the changes must be non-trivial, or "significant" as the [OpenJDK Project description](https://openjdk.org/projects/) says, and the definition of significant is subjective, the general recommendation is to wait with a [Committer](https://openjdk.org/bylaws#committer) nomination until there's at least 10-12 changes pushed to have some margin for different interpretations of "significant". In practice though, we have seen several examples where the number of significant changes hasn't been the dominating factor in a [Committer](https://openjdk.org/bylaws#committer) vote. A [Contributor's](https://openjdk.org/bylaws#contributor) work in another [OpenJDK Project](https://openjdk.org/bylaws#project) may also be relevant for the vote. What the vote should ultimately test is the [Contributor's](https://openjdk.org/bylaws#contributor) commitment to the [OpenJDK Project](https://openjdk.org/bylaws#project) for which the vote applies - is it believed that the person is dedicated and willing to spend time and effort on the [Project](https://openjdk.org/bylaws#project)? Is the person believed to be a good citizen of the [Project](https://openjdk.org/bylaws#project)? It's always a good idea to seek the advice of a [Sponsor](https://openjdk.org/bylaws#sponsor) who can guide you through the process to becoming a [Committer](https://openjdk.org/bylaws#committer) - you will need one to run the Committer vote anyway. They will probably also have a better idea of what constitutes a "significant" change.
-Once you have the required changes, a Committer in the project can start a vote by sending an email proposing that you should become a Committer. The email should follow the template found in the [OpenJDK Project description](https://openjdk.org/projects/#project-committer).
+Once you have the required changes, a [Committer](https://openjdk.org/bylaws#committer) in the [Project](https://openjdk.org/bylaws#project) can start a vote by sending an email proposing that you should become a [Committer](https://openjdk.org/bylaws#committer). The email should follow the template found in the [OpenJDK Project description](https://openjdk.org/projects/#project-committer).
-A Committer is allowed to push changes without the aid of a sponsor. A Committer is also allowed to nominate other non-Committers to become Committers in the project.
+A [Committer](https://openjdk.org/bylaws#committer) is allowed to push changes without the aid of a [Sponsor](https://openjdk.org/bylaws#sponsor). A [Committer](https://openjdk.org/bylaws#committer) is also allowed to nominate other non-Committers to become [Committers](https://openjdk.org/bylaws#committer) in the [Project](https://openjdk.org/bylaws#project).
### Becoming a Reviewer
-To become a [Reviewer](https://openjdk.org/bylaws#reviewer) you must show a track record of sound and correct judgment calls as mentioned above. Being a good Committer doesn't necessarily make you a good Reviewer. As a Reviewer you have the power to approve changes for inclusion into the project source code. This means that a Reviewer needs to be able to judge the quality and appropriateness of any proposed change, not just the mechanics of the code.
+To become a [Reviewer](https://openjdk.org/bylaws#reviewer) you must show a track record of sound and correct judgment calls as mentioned above. Being a good [Committer](https://openjdk.org/bylaws#committer) doesn't necessarily make you a good [Reviewer](https://openjdk.org/bylaws#reviewer). As a [Reviewer](https://openjdk.org/bylaws#reviewer) you have the power to approve changes for inclusion into the Project source code. This means that a [Reviewer](https://openjdk.org/bylaws#reviewer) needs to be able to judge the quality and appropriateness of any proposed change, not just the mechanics of the code.
-The assumption is that after having produced 32 significant changes one should have become familiar with the process around reviews and the requirements around getting a change approved. This should really be seen as a minimum requirement though. A more practical consideration would be to look at whether the non-trivial commits of a potential Reviewer are accepted largely intact or whether they are always being refined by the review process. There may be cases where it will take significantly more than 32 changes for a Committer to be ready to become a Reviewer.
+The assumption is that after having produced 32 significant changes one should have become familiar with the process around reviews and the requirements around getting a change approved. This should really be seen as a minimum requirement though. A more practical consideration would be to look at whether the non-trivial commits of a potential [Reviewer](https://openjdk.org/bylaws#reviewer) are accepted largely intact or whether they are always being refined by the review process. There may be cases where it will take significantly more than 32 changes for a [Committer](https://openjdk.org/bylaws#committer) to be ready to become a [Reviewer](https://openjdk.org/bylaws#reviewer).
-Once you are deemed ready, a Reviewer in the project can start a vote by sending an email proposing that you should become a Reviewer. The email should follow the template found in the [OpenJDK Project description](https://openjdk.org/projects/#project-reviewer).
+Once you are deemed ready, a [Reviewer](https://openjdk.org/bylaws#reviewer) in the [Project](https://openjdk.org/bylaws#project) can start a vote by sending an email proposing that you should become a [Reviewer](https://openjdk.org/bylaws#reviewer). The email should follow the template found in the [OpenJDK Project description](https://openjdk.org/projects/#project-reviewer).
### Non-trivial/Significant changes
@@ -67,7 +67,7 @@ Instead of describing the significant change (because that's quite difficult to
* Purely aesthetic changes like renaming or fixing indentation
* Repeated follow-up bugfixes from earlier changes
-* Larger changes where only a non-significant portion of the work was done by the Contributor under vote
+* Larger changes where only a non-significant portion of the work was done by the [Contributor](https://openjdk.org/bylaws#contributor) under vote
* Trivial backports of someone else's changes
::: {.box}
diff --git a/src/guide/jbs-jdk-bug-system.md b/src/guide/jbs-jdk-bug-system.md
index 22d58a5..e921c92 100644
--- a/src/guide/jbs-jdk-bug-system.md
+++ b/src/guide/jbs-jdk-bug-system.md
@@ -7,14 +7,11 @@
* [JDK Bug System (JBS)](https://bugs.openjdk.org/)
:::
-[JBS](https://bugs.openjdk.org/) is a public issue tracker used by many OpenJDK projects and is open for anyone to read and search. To get write access you need to be registered in the [OpenJDK Census](https://openjdk.org/census) by becoming, for instance, an [Author](https://openjdk.org/bylaws#author) in an OpenJDK [Project](https://openjdk.org/bylaws#project).
+[JBS](https://bugs.openjdk.org/) is a public issue tracker used by many [OpenJDK Projects](https://openjdk.org/bylaws#project) and is open for anyone to read and search. To get write access you need to be registered in the [OpenJDK Census](https://openjdk.org/census) by becoming, for instance, an [Author](https://openjdk.org/bylaws#author) in an [OpenJDK Project](https://openjdk.org/bylaws#project).
## Filing an issue
-When a new failure is found, or an improvement identified, an issue should be filed to describe and track its resolution.
-Depending on your role in OpenJDK you can either use the [Bug Report Tool](https://bugreport.java.com/) or, if you
-are registered in the [OpenJDK Census](https://openjdk.org/census), you can report the issue directly in [JBS](https://bugs.
-openjdk.org/).
+When a new failure is found, or an improvement identified, an issue should be filed to describe and track its resolution. Depending on your role in OpenJDK you can either use the [Bug Report Tool](https://bugreport.java.com/) or, if you are registered in the [OpenJDK Census](https://openjdk.org/census), you can report the issue directly in [JBS](https://bugs.openjdk.org/).
When filing an issue, try to make the report as complete as possible in order to make it easier to triage, investigate and resolve the issue.
@@ -204,7 +201,7 @@ style ClosedIncomplete fill:lightgreen
## Triaging an issue
-For most JDK areas, triage is performed on a regular basis (at least weekly) by triage teams. Each triage team consists of contributors who are area experts for a specific area or feature. If you haven't been selected to be part of a triage team for a specific area *you shouldn't be triaging bugs in that area*.
+For most JDK areas, triage is performed on a regular basis (at least weekly) by triage teams. Each triage team consists of [Contributors](https://openjdk.org/bylaws#contributor) who are area experts for a specific area or feature. If you haven't been selected to be part of a triage team for a specific area *you shouldn't be triaging bugs in that area*.
When triaging an issue, first give it a general review.
@@ -226,8 +223,8 @@ Now that the issue is in the right component and has the basic information, the
* If the bug also exists in older versions it may require [backporting].
* The decision to backport to a release should be made inline with the guidelines of the lead for that release.
* There are two options for creating backport issues to track the backport: one is to create it manually once it's agreed that the bug should be backported; the second, is to let the bots create the backport issue once you push the fix to the repo (see [Working with backports in JBS]). In most cases, letting the bots create the backport issue is preferred.
- * For project internal changes intended to be pushed to a project repository rather than the JDK or JDK Updates repositories, the [Fix Version/s]{.jbs-field} should be set to [internal]{.jbs-value}, or if the project is large enough to have its own [repo-*]{.jbs-value} fix version, use that.
- * Only one [Fix Version/s]{.jbs-field} should ever be set, if the issue is to be fixed in additional releases then a separate backport must be created (see [Working with backports in JBS]). There are exceptions to this rule for CSRs and Release Notes.
+ * For Project internal changes intended to be pushed to a Project repository rather than the JDK or JDK Updates repositories, the [Fix Version/s]{.jbs-field} should be set to [internal]{.jbs-value}, or if the [Project](https://openjdk.org/bylaws#project) is large enough to have its own [repo-*]{.jbs-value} fix version, use that.
+ * Only one [Fix Version/s]{.jbs-field} should ever be set, if the issue is to be fixed in additional releases then separate backport issues must be created (see [Working with backports in JBS]). There are exceptions to this rule for CSRs and Release Notes.
1. Make sure the bug has all the required labels – see [JBS Label Dictionary].
* Bugs where behavior has _incorrectly_ changed from a previous build or release: [[regression]{.jbs-label}](#regression)
* Changes that don't affect product code, but are only against the regression test, or problem-listing: [[noreg-self]{.jbs-label}](#noreg-self)
@@ -268,7 +265,7 @@ Once the work on an issue has been completed the issues [Status]{.jbs-field} sho
| Resolution | Use with status | Covers |
|:-|:-|:----------|
-| [Fixed]{.jbs-value} | [Resolved]{.jbs-value} / [Closed]{.jbs-value} | The [Fixed]{.jbs-value} resolution should be used **only** if a change has been integrated in a repo to address the issue. For the JDK project in almost all cases the bots will transition the issue to [Resolved]{.jbs-value}/[Fixed]{.jbs-value} when the changeset is pushed to the repo. An issue in [Resolved]{.jbs-value}/[Fixed]{.jbs-value} state needs to go through [verification](#verifying-an-issue) to end up as [Closed]{.jbs-value}/[Fixed]{.jbs-value}.<br />If there isn't a fix in the repo (and so no associated changeset) then the issue should **not** be marked as [Fixed]{.jbs-field}. |
+| [Fixed]{.jbs-value} | [Resolved]{.jbs-value} / [Closed]{.jbs-value} | The [Fixed]{.jbs-value} resolution should be used **only** if a change has been integrated in a repo to address the issue. For the JDK Project in almost all cases the bots will transition the issue to [Resolved]{.jbs-value}/[Fixed]{.jbs-value} when the changeset is pushed to the repo. An issue in [Resolved]{.jbs-value}/[Fixed]{.jbs-value} state needs to go through [verification](#verifying-an-issue) to end up as [Closed]{.jbs-value}/[Fixed]{.jbs-value}.<br />If there isn't a fix in the repo (and so no associated changeset) then the issue should **not** be marked as [Fixed]{.jbs-field}. |
| [Won't Fix]{.jbs-value} | [Closed]{.jbs-value} | Used when the issue is describing behavior which, while maybe problematic or not ideal, isn't going to be changed - for compatibility reasons for example. |
| [Duplicate]{.jbs-value} | [Closed]{.jbs-value} | Used to indicate that the same issue is described in another JBS issue. See [Closing issues as duplicates] for more information. |
| [Incomplete]{.jbs-value} | [Resolved]{.jbs-value} / [Closed]{.jbs-value} | Used to indicate that the JBS issue doesn't contain enough information to work on the issue. See [Closing incomplete issues] for more information. |
@@ -327,13 +324,13 @@ This table contains some frequently used JBS labels and their meaning. Please he
<tr>
<td class="dictionary">[*(Area)*[-interest]{.jbs-label}]{#area-interest}</td>
<td class="dictionary">
- Used to indicate that an area (usually a team or project) is interested in the issue. This label doesn't indicate ownership of the issue. E.g., [redhat-interest]{.jbs-label}, [azul-interest]{.jbs-label}, [coin-interest]{.jbs-label}
+ Used to indicate that an area (usually a team or [Project](https://openjdk.org/bylaws#project)) is interested in the issue. This label doesn't indicate ownership of the issue. E.g., [redhat-interest]{.jbs-label}, [azul-interest]{.jbs-label}, [coin-interest]{.jbs-label}
</td>
</tr>
<tr>
<td class="dictionary">[*(Area)*[-related]{.jbs-label}]{#area-related}</td>
<td class="dictionary">
- Used to indicate that an issue is related to a specific area (usually a feature or project). This label doesn't indicate ownership of the issue. E.g., [graal-related]{.jbs-label}, [testcolo-related]{.jbs-label}, [doc-related]{.jbs-label}
+ Used to indicate that an issue is related to a specific area (usually a feature or [Project](https://openjdk.org/bylaws#project)). This label doesn't indicate ownership of the issue. E.g., [graal-related]{.jbs-label}, [testcolo-related]{.jbs-label}, [doc-related]{.jbs-label}
</td>
</tr>
<!-- Release -->
@@ -348,7 +345,7 @@ This table contains some frequently used JBS labels and their meaning. Please he
[*(Rel)*[-critical-approved]{.jbs-label}]{#rel-critical-approved}<br />
[*(Rel)*[-critical-watch]{.jbs-label}]{#rel-critical-watch}</td>
<td class="dictionary">
- Used in the rampdown phases of specific releases to request approval of changes that requires project lead approval (or similar) to be included. *(Rel)* is the release in question. E.g., [jdk11-critical-request]{.jbs-label}
+ Used in the ramp down phases of specific releases to request approval of changes that requires Project lead approval (or similar) to be included. *(Rel)* is the release in question. E.g., [jdk11-critical-request]{.jbs-label}
*(Rel)*[-critical-approved]{.jbs-label} is used to signal that the change has been approved for inclusion. E.g., [jdk11-critical-approved]{.jbs-label}<br />
*(Rel)*[-critical-watch]{.jbs-label} is used for issues that must get into a specific release but risk running late. The label is used while the issue is still in progress and is replaced with *(Rel)*[-critical-request]{.jbs-label} once the issue is resolved. E.g., [jdk11-critical-watch]{.jbs-label}
@@ -361,7 +358,7 @@ This table contains some frequently used JBS labels and their meaning. Please he
[*(Rel)*[-defer-yes]{.jbs-label}]{#rel-defer-yes}<br />
[*(Rel)*[-defer-no]{.jbs-label}]{#rel-defer-no}</td>
<td class="dictionary">
- Used to request deferral of changes that requires project lead approval (or similar) to defer. *(Rel)* is the release in question. E.g., [jdk12-defer-request]{.jbs-label}
+ Used to request deferral of changes that requires Project lead approval (or similar) to defer. *(Rel)* is the release in question. E.g., [jdk12-defer-request]{.jbs-label}
*(Rel)*[-defer-yes]{.jbs-label} and *(Rel)*[-defer-no]{.jbs-label} are used to indicate wether the deferral has been approved or not. E.g., [jdk12-defer-yes]{.jbs-label}
@@ -374,7 +371,7 @@ This table contains some frequently used JBS labels and their meaning. Please he
[*(Rel)*[-enhancement-yes]{.jbs-label}]{#rel-enhancement-yes}<br />
[*(Rel)*[-enhancement-no]{.jbs-label}]{#rel-enhancement-no}</td>
<td class="dictionary">
- Used in the rampdown phases to request the late inclusion of an enhancement. *(Rel)* is the release in question. E.g., [jdk10-enhancement-request]{.jbs-label}
+ Used in the ramp down phases to request the late inclusion of an enhancement. *(Rel)* is the release in question. E.g., [jdk10-enhancement-request]{.jbs-label}
*(Rel)*[-enhancement-yes]{.jbs-label} and *(Rel)*[-enhancement-no]{.jbs-label} are used to indicate the response on the request. E.g., [jdk10-enhancement-yes]{.jbs-label}, [jdk10-enhancement-no]{.jbs-label}
@@ -388,7 +385,7 @@ This table contains some frequently used JBS labels and their meaning. Please he
[*(Rel)*[-fix-yes]{.jbs-label}]{#rel-fix-yes}<br />
[*(Rel)*[-fix-no]{.jbs-label}]{#rel-fix-no}</td>
<td class="dictionary">
- Used in rampdown phase 2 to indicate that an issue would be of interest to get integrated into release *(Rel)*. E.g., [jdk12u-fix-request]{.jbs-label}
+ Used in ramp down phase 2 to indicate that an issue would be of interest to get integrated into release *(Rel)*. E.g., [jdk12u-fix-request]{.jbs-label}
*(Rel)*[-fix-SQE-ok]{.jbs-label} is used to indicate that the issue will be covered by the test plan for *(Rel)*. E.g., [jdk12u-fix-SQE-ok]{.jbs-label}<br />
*(Rel)*[-fix-yes]{.jbs-label} and *(Rel)*[-fix-no]{.jbs-label} are used to indicate wether an issue has been approved for backport to *(Rel)*. E.g., [jdk12u-fix-yes]{.jbs-label}
@@ -760,7 +757,7 @@ Examples: If a bug fix only corrects a change in the build system, then add the
<td class="dictionary">
Used to indicate which tier in the `jdk/jdk` CI pipeline a test failure has been seen in. Lower tiers would in general mean higher urgency to fix the issue. E.g., [tier1]{.jbs-label}, [tier2]{.jbs-label}
- Please note that these labels are reserved for bugs seen in the `jdk/jdk` CI pipeline. Use *(Rel)*[-tier1] for other CI pipelines, where *(Rel)* is the name of the pipeline. E.g. [8u-tier1]{.jbs-label}
+ Please note that these labels are reserved for bugs seen in the `jdk/jdk` CI pipeline. Use *(Rel)*[-tier]{.jbs-label}`[1-8]` for other CI pipelines, where *(Rel)* is the name of the pipeline. E.g. [8u-tier1]{.jbs-label}
</td>
</tr>
<!-- U -->
diff --git a/src/guide/mailing-lists.md b/src/guide/mailing-lists.md
index fa383dc..3ac7bc9 100644
--- a/src/guide/mailing-lists.md
+++ b/src/guide/mailing-lists.md
@@ -6,30 +6,30 @@
* [OpenJDK Mailing Lists Manager](https://mail.openjdk.org/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.org/bylaws#participant) in the [Bylaws](https://openjdk.org/bylaws). As a general recommendation we suggest to subscribe to [announce](https://mail.openjdk.org/mailman/listinfo/announce), [discuss](https://mail.openjdk.org/mailman/listinfo/discuss), and the `-dev` lists covering your explicit area of interest. All OpenJDK mailing lists are found here:
+The mailing lists are the key communications mechanism for all OpenJDK work. All participation in an [OpenJDK Project](https://openjdk.org/bylaws#project) starts with joining the relevant mailing list. A subscriber to an OpenJDK mailing list is referred to as a [Participant](https://openjdk.org/bylaws#participant) in the [Bylaws](https://openjdk.org/bylaws). As a general recommendation we suggest to subscribe to [announce](https://mail.openjdk.org/mailman/listinfo/announce), [discuss](https://mail.openjdk.org/mailman/listinfo/discuss), and the `-dev` lists covering your explicit area of interest. All OpenJDK mailing lists are found here:
> [`mail.openjdk.org`](https://mail.openjdk.org/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.
+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](https://github.com).
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.
+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](https://openjdk.org/bylaws#project) that owns the list or a specific area of interest that the list focuses on. The suffix is explained below. Not all [Projects](https://openjdk.org/bylaws#project) 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.
+> : 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.
+> : Technical discussions around the usage of the Project artifacts.
> `-discuss`
-> : General discussions around the project. The special case `discuss@openjdk.org` is used for general discussions around OpenJDK. Discussions around new project proposals usually happen here.
+> : General discussions around the [Project](https://openjdk.org/bylaws#project). The special case `discuss@openjdk.org` is used for general discussions around OpenJDK. Discussions around new Project proposals usually happen here.
> `-changes`
-> : Changeset notifications from the source code repositories maintained by the project.
+> : Changeset notifications from the source code repositories maintained by the [Project](https://openjdk.org/bylaws#project).
> `-announce`
-> : General project announcements. These lists are tightly moderated and are expected to be low traffic. The special case `announce@openjdk.org` is used for announcements for OpenJDK.
+> : General Project announcements. These lists are tightly moderated and are expected to be low traffic. The special case `announce@openjdk.org` is used for announcements for OpenJDK.
> `-experts`
> : Expert group discussions. The list is restricted; only members of the expert group can subscribe.
diff --git a/src/guide/project-maintenance.md b/src/guide/project-maintenance.md
index ab404f9..bfd3fb8 100644
--- a/src/guide/project-maintenance.md
+++ b/src/guide/project-maintenance.md
@@ -1,16 +1,16 @@
# Project Maintenance
-Many OpenJDK projects build on top of the JDK source code for instance to produce new language features, like projects [Amber](https://openjdk.org/projects/amber/) and [Valhalla](https://openjdk.org/projects/valhalla/). When doing this there are a number of common workflows that are dealt with by most project maintainers. For instance, updating the codebase (merging) to bring in the latest changes from the upstream JDK project.
+Many [OpenJDK Projects](https://openjdk.org/bylaws#project) build on top of the JDK source code for instance to produce new language features, like Projects [Amber](https://openjdk.org/projects/amber/) and [Valhalla](https://openjdk.org/projects/valhalla/). When doing this there are a number of common workflows that are dealt with by most Project maintainers. For instance, updating the codebase (merging) to bring in the latest changes from the upstream JDK Project.
-## Merging JDK mainline into a project repository
+## Merging JDK mainline into a Project repository
-Merging changes from one git repository to another is basically the same thing as getting your own changes merged into the project repository, with the slight twist that you don't write all the changes yourself, you just pull them from somewhere else.
+Merging changes from one git repository to another is basically the same thing as getting your own changes merged into the Project repository, with the slight twist that you don't write all the changes yourself, you just pull them from somewhere else.
-In this example we'll use a separate clone of the project repository to perform the merge in. This can be done using branches as well, but let's keep it simple for now.
+In this example we'll use a separate clone of the Project repository to perform the merge in. This can be done using branches as well, but let's keep it simple for now.
### Init - done once
-First set up your personal fork of the project repository, in this example called `my-project`. If you already are a Contributor to the project you most likely have this set up. If not, see [Cloning the JDK] for details on how to do that.
+First set up your personal fork of the Project repository, in this example called `my-project`. If you already are a [Contributor](https://openjdk.org/bylaws#contributor) to the [Project](https://openjdk.org/bylaws#project) you most likely have this set up. If not, see [Cloning the JDK] for details on how to do that.
~~~shell
git clone git@github.com:OpenDuke/my-project.git project-merge
@@ -23,7 +23,7 @@ We clone the personal fork (in this case we clone OpenDuke's personal fork) into
### Performing the merge
-The clone we set up above is used each time you want to bring changes from mainline in to your project. This is done by first pulling the changes from mainline and then pushing to your personal fork. A regular PR will then be created which you can integrate into your main project repository. It sounds easy, and it is, but there are a few details below to keep in mind.
+The clone we set up above is used each time you want to bring changes from mainline in to your [Project](https://openjdk.org/bylaws#project). This is done by first pulling the changes from mainline and then pushing to your personal fork. A regular PR will then be created which you can integrate into your main Project repository. It sounds easy, and it is, but there are a few details below to keep in mind.
~~~shell
cd project-merge
@@ -33,7 +33,7 @@ git switch -c Merge_mainline
git fetch mainline
~~~
-We start by updating the local fork with the latest changes from the main project repository. Note that we then create a new branch "`Merge_mainline`" in which the merge will happen. Finally we fetch all new changes from mainline.
+We start by updating the local fork with the latest changes from the main Project repository. Note that we then create a new branch "`Merge_mainline`" in which the merge will happen. Finally we fetch all new changes from mainline.
Merging from what ever is latest isn't usually a good idea, mainline code is not "clean" for any given commit. Merging JDK tags ensures you have a known quality, those tagged commits are known to compile and pass tests. Therefore, next we check which tags have not been merged yet.
@@ -59,15 +59,15 @@ And finally we initiate the actual merge.
git merge $TAG
~~~
-The commands above will likely run without a hitch up until the final `git merge`. This is where you need to combine the changes that were made in mainline with the changes that have been made in your project repository. If there are no conflicts you're in luck, then the merge will be completely automated and you will end up with a committed merge. If there are conflicts however you'll need to manually go through the files where the conflicts are and make sure you select the correct version for each change. Using `git status` you can see what files that need to be merged. Depending on how much code your project has touched, this can be quite a bit of work.
+The commands above will likely run without a hitch up until the final `git merge`. This is where you need to combine the changes that were made in mainline with the changes that have been made in your Project repository. If there are no conflicts you're in luck, then the merge will be completely automated and you will end up with a committed merge. If there are conflicts however you'll need to manually go through the files where the conflicts are and make sure you select the correct version for each change. Using `git status` you can see what files that need to be merged. Depending on how much code your [Project](https://openjdk.org/bylaws#project) has touched, this can be quite a bit of work.
For complicated merges, see [Sharing the work] below.
### Test before push
-Regardless of if you encountered conflicts or not, you should always build and test your merge before pushing it to your project repository. Testing needs to be done even when there are no textual conflicts as changes like for instance a rename can result in a compile or test error without any conflict. One could argue that `git merge --no-commit` could be used and have logical errors fixed in the merge commit. However, a subsequent "Fix logical merge errors" commit, is in fact more useful, as it clearly shows the project specific adjustments needed for incoming changes.
+Regardless of if you encountered conflicts or not, you should always build and test your merge before pushing it to your Project repository. Testing needs to be done even when there are no textual conflicts as changes like for instance a rename can result in a compile or test error without any conflict. One could argue that `git merge --no-commit` could be used and have logical errors fixed in the merge commit. However, a subsequent "Fix logical merge errors" commit, is in fact more useful, as it clearly shows the Project specific adjustments needed for incoming changes.
-It's always okay to have further commits to clean up after a merge. Hiding a large amount of reworking project code to fit with upstream changes in a single merge commit will make it hard for further errors post integration to be identified.
+It's always okay to have further commits to clean up after a merge. Hiding a large amount of reworking Project code to fit with upstream changes in a single merge commit will make it hard for further errors post integration to be identified.
### The commit, push, and PR
@@ -78,13 +78,13 @@ git commit -m "Merge"
git push --set-upstream origin Merge_mainline
~~~
-Now it's time to create the PR on GitHub. Just opening the PR page in your browser will most often be enough to see a message about new code that was pushed to your personal fork. Click the button to create the PR.
+Now it's time to create the PR on [GitHub](https://github.com). Just opening the PR page in your browser will most often be enough to see a message about new code that was pushed to your personal fork. Click the button to create the PR.
Make sure the PR title starts with "Merge". You may have noticed that when you integrate a "normal" PR into an OpenJDK repository, all commits that have been done in that PR will be squashed into a single commit. For normal changes this is a good thing as each PR normally corresponds to a single JBS issue, but for a merge it would be highly undesirable to squash all the different commits that you pull in from mainline. A PR with a title that starts with "Merge" won't be squashed. That means that all the changes that you brought over will remain separate changes.
-It's always a good idea to also include what was merged in the title of the PR. If you for instance is pulling in JDK mainline into your project repository it's likely (because it's in general a good idea) that you choose some stable EA tag in mainline to merge. Your PR title could then be something like "Merge jdk-21+2".
+It's always a good idea to also include what was merged in the title of the PR. If you for instance is pulling in JDK mainline into your Project repository it's likely (because it's in general a good idea) that you choose some stable EA tag in mainline to merge. Your PR title could then be something like "Merge jdk-21+2".
-Whether a merge requires a review or not is up to your project lead to decide. Many projects don't require this so the GitHub bots will allow you to push the merge as soon as the [GHA](#github-actions)s are done. (They actually allow you to push even before the GHAs are done, but that's in general not a good idea.)
+Whether a merge requires a review or not is up to your Project lead to decide. Many [Projects](https://openjdk.org/bylaws#project) don't require this so the GitHub bots will allow you to push the merge as soon as the [GHA](#github-actions)s are done. (They actually allow you to push even before the GHAs are done, but that's in general not a good idea.)
Once the PR has been integrated, you can clean up your fork and its clone in preparation for the next merge.
@@ -98,7 +98,7 @@ These commands will remove the temporary branch that we created to perform the m
### Sharing the work
-When conflicts take place in areas requiring specialized knowledge you may need help from other Contributors. Backing up the original conflicts will help if you find yourself "in too deep", and need assistance from other Contributors. You can add and later remove these backups, along with a readme describing the merge status, to the actual merge branch to aid communication (i.e. you may not be able to compile certain components).
+When conflicts take place in areas requiring specialized knowledge you may need help from other [Contributors](https://openjdk.org/bylaws#contributor). Backing up the original conflicts will help if you find yourself "in too deep", and need assistance from other [Contributors](https://openjdk.org/bylaws#contributor). You can add and later remove these backups, along with a readme describing the merge status, to the actual merge branch to aid communication (i.e. you may not be able to compile certain components).
Something like the following shell one-liner can be used to perform the backup.
@@ -110,7 +110,7 @@ Below are two different methods of collaborating on a merge described. Please no
#### 1. Parking a merge with conflicts in place
-"Park" the conflicts, unresolved, in a personal fork, and let others do the further work (by sending you a patch, or opening your personal fork up to push from other Contributors). Do this by keeping a list of unresolved conflicts (perhaps checking in said list to describe the merge state), and then marking them as resolved in git, committing, and pushing them to your personal fork. E.g. `git add $UNRESOLVED_FILES; git commit; git push`
+"Park" the conflicts, unresolved, in a personal fork, and let others do the further work (by sending you a patch, or opening your personal fork up to push from other [Contributors](https://openjdk.org/bylaws#contributor)). Do this by keeping a list of unresolved conflicts (perhaps checking in said list to describe the merge state), and then marking them as resolved in git, committing, and pushing them to your personal fork. E.g. `git add $UNRESOLVED_FILES; git commit; git push`
**Pros:** All unresolved conflicts are stated and can be worked on by multiple parties, all at once.
@@ -126,7 +126,7 @@ An alternative to parking a merge with conflicts in place, is to incrementally m
* Find the troublesome change: `git log --topo-order --pretty=oneline --reverse $(current_branch)..$TAG`
* Merge up to the previous change, commit and push.
* Ask others to continue the merge from the troubled change forward, how far forward is up you of course, either just that troublesome change, or the rest of the merge up to the $TAG.
-* Rinse and repeat: There may appear further conflicts requiring other Contributors help.
+* Rinse and repeat: There may appear further conflicts requiring other [Contributors'](https://openjdk.org/bylaws#contributor) help.
**Pros:** All commits in the merge branch compile and test, you always have a working branch.
diff --git a/src/guide/release-notes.md b/src/guide/release-notes.md
index 000625f..a8c4a96 100644
--- a/src/guide/release-notes.md
+++ b/src/guide/release-notes.md
@@ -11,7 +11,7 @@
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.
+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
@@ -69,7 +69,7 @@ The following are general practices that should be followed when creating releas
## Advanced options
* JEP release notes
* [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 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.
* Single release note for multiple changes
* A link to the parent issue that the note is a sub-task of, will be placed alongside the summary in the release notes. If note relates to additional changes, then add them as [Relates]{.jbs-field} links to the note and add the label [RN-MultipleLinks]{.jbs-label} - see [JDK-8284975](https://bugs.openjdk.org/browse/JDK-8284975) as an example.
diff --git a/src/guide/testing-the-jdk.md b/src/guide/testing-the-jdk.md
index 6848c60..fef9541 100644
--- a/src/guide/testing-the-jdk.md
+++ b/src/guide/testing-the-jdk.md
@@ -171,9 +171,9 @@ The second example above runs tests which match the regexp `$X.*` on a specific
## GitHub actions
-GitHub has a feature called **GitHub actions** (GHA) that can be used to automate testing. The GHA is executed whenever a push is made to a branch in your repository. The bots will show the results of the GHA in your PR when you create or update it. The GHA in the JDK project is configured to run a set of tests that is commonly known as **tier 1**. This is a relatively fast, small set of tests that tries to verify that your change didn't break the JDK completely. In tier 1 the JDK is built on a small set of platforms including (but not necessarily limited to) Linux, Windows, and MacOS, and a few tests are executed using these builds. There's also a set of other platforms for which GHA does cross-complilation builds.
+[GitHub](https://github.com) has a feature called **GitHub actions** (GHA) that can be used to automate testing. The GHA is executed whenever a push is made to a branch in your repository. The bots will show the results of the GHA in your PR when you create or update it. The GHA in the JDK Project is configured to run a set of tests that is commonly known as **tier 1**. This is a relatively fast, small set of tests that tries to verify that your change didn't break the JDK completely. In tier 1 the JDK is built on a small set of platforms including (but not necessarily limited to) Linux, Windows, and MacOS, and a few tests are executed using these builds. There's also a set of other platforms for which GHA does cross-complilation builds.
-In addition to the testing you run manually before publishing your changes, it's recommended that you take advantage of this automated testing that the GHA offers. This will for instance allow you to run tests on platforms that you may not otherwise have access to. To enable this on your personal fork of the JDK on GitHub go to the "Actions" tab and click the big green button saying "I understand my workflows, go ahead and enable them". If you don't understand these workflows there's a link to the actual file that describes them right below the green button.
+In addition to the testing you run manually before publishing your changes, it's recommended that you take advantage of this automated testing that the GHA offers. This will for instance allow you to run tests on platforms that you may not otherwise have access to. To enable this on your personal fork of the JDK on [GitHub](https://github.com) go to the "Actions" tab and click the big green button saying "I understand my workflows, go ahead and enable them". If you don't understand these workflows there's a link to the actual file that describes them right below the green button.
In case of failures in the GHA it's always a good start to try to reproduce the failure locally on a machine where you have better control and easier access to a debug environment. There have been cases where the GHA has failed due to issues unrelated to the change being tested, e.g. because the GHA environment was updated and changes were needed to the JDK GHA configuration. The configuration is in general updated fairly quickly, so in cases were you can't reproduce the failure locally, consider re-running the GHA later.
@@ -302,7 +302,7 @@ After a failure is handled by excluding a test, the main JBS issue should be re-
If a change causes a regression that can't be fixed within reasonable time, the best way to handle the regression can be to back out the change. Backing out means that the inverse (anti-delta) of the change is pushed to effectively undo the change in the repository. There are two parts to this task, how to do the bookkeeping in JBS, and how to do the actual backout in git or Mercurial.
-The backout is a regular change and will have to go through the standard code review process, but is considered a [trivial](#trivial) change. The rationale is that a backout is usually urgent in nature and the change itself is automatically generated. In areas where two reviewers are normally required, only one additional Reviewer is required for a backout since the person who is performing the backout also will review the change.
+The backout is a regular change and will have to go through the standard code review process, but is considered a [trivial](#trivial) change. The rationale is that a backout is usually urgent in nature and the change itself is automatically generated. In areas where two reviewers are normally required, only one additional [Reviewer](https://openjdk.org/bylaws#reviewer) is required for a backout since the person who is performing the backout also will review the change.
### How to work with JBS when a change is backed out
diff --git a/src/guide/working-with-pull-requests.md b/src/guide/working-with-pull-requests.md
index 29cf603..3316c0b 100644
--- a/src/guide/working-with-pull-requests.md
+++ b/src/guide/working-with-pull-requests.md
@@ -6,7 +6,7 @@
* [Skara documentation on PR commands](https://wiki.openjdk.org/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 section 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.
+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](https://github.com). This section assumes that you have previous experience from using git and [GitHub](https://github.com), 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.
This section also assumes that you have already read [I have a patch, what do I do?] and followed **all** the steps there.
@@ -14,7 +14,7 @@ This section also assumes that you have already read [I have a patch, what do I
All code reviews in OpenJDK are done in public. Once you open your PR for public review the internet can see it and comment on it. Make sure your code is ready for it. Look through your comments, make sure that temporary code is gone, and make sure you have sanitized your method and variable names. Also, make sure you understand your code. Why is it working? What are the potential pitfalls? What are the edge-cases? If you haven't already answered all these questions in the mail conversation that preceded this PR, it's likely that you will need to answer them during the review.
-It's also worth taking the extra time to see if the change can be split into a few different separate changes. A large change will take more effort and thus attract fewer Reviewers. Smaller changes will get reviewed faster and get better quality reviews. You can compare proposing a single large change to proposing ten individual small unrelated changes. What happens in practice when all these ten changes are presented as one PR is that there's a focus on say 5-6 of these smaller changes and no one really looks hard at the other 4-5. For complexity, even small changes that are hard to understand and test may be risky.
+It's also worth taking the extra time to see if the change can be split into a few different separate changes. A large change will take more effort and thus attract fewer [Reviewers](https://openjdk.org/bylaws#reviewer). Smaller changes will get reviewed faster and get better quality reviews. You can compare proposing a single large change to proposing ten individual small unrelated changes. What happens in practice when all these ten changes are presented as one PR is that there's a focus on say 5-6 of these smaller changes and no one really looks hard at the other 4-5. For complexity, even small changes that are hard to understand and test may be risky.
The timing of your change will also affect the availability of reviewers. The JDK runs on a [six-months release cadence](#release-cycle). During the months around the start of the ramp down phase most area experts will be busy working on their own changes and reviewing major features that are planned for the release. If you propose a change during this period (basically May-June, or November-December) it may take a long time before you get the required reviews.
@@ -48,13 +48,13 @@ Creating the PR is essentially the same as asking a large group of people to sta
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 to labeled groups as long as the PR is in `DRAFT` mode.
+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 to labeled [Groups](https://openjdk.org/bylaws#group) 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.
+ There are changes that span across several areas, for example wide spread cleanups or the introduction of a new language 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**
@@ -62,7 +62,7 @@ If you have an actual reason to create a PR before the change is all done, make
#. **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.
+ The description of the PR should state what problem is being solved and shortly describe how it's solved. [Reviewers](https://openjdk.org/bylaws#reviewer) 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.
@@ -70,9 +70,9 @@ If you have an actual reason to create a PR before the change is all done, make
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**
+#. **Make sure all relevant [Groups](https://openjdk.org/bylaws#group) 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.org/display/SKARA/Pull+Request+Commands#PullRequestCommands-/label) if needed. Consult the [Code Owners](#code-owners) section if you are unsure of who owns the code you are changing.
+ The bot will make an attempt to include the [Groups](https://openjdk.org/bylaws#group) 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](https://openjdk.org/bylaws#group) as well, and the mapping from source to [Groups](https://openjdk.org/bylaws#group) isn't always perfect, so make sure all relevant [Groups](https://openjdk.org/bylaws#group) have been included, and add new labels using [`/label`](https://wiki.openjdk.org/display/SKARA/Pull+Request+Commands#PullRequestCommands-/label) if needed. Consult the [Code Owners](#code-owners) section if you are unsure of who owns the code you are changing.
#. **Allow enough time for review**
@@ -80,7 +80,7 @@ If you have an actual reason to create a PR before the change is all done, make
#. **Get the required reviews**
- At least one Reviewer knowledgeable in each area being changed must approve every change. 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.
+ At least one [Reviewer](https://openjdk.org/bylaws#reviewer) knowledgeable in each area being changed must approve every change. Some areas (e.g. Client and HotSpot) require two reviewers in most cases, so be sure to read the relevant [OpenJDK Group](https://openjdk.org/bylaws#group) pages for advice or ask your [Sponsor](https://openjdk.org/bylaws#sponsor).
Be open to comments and polite in replies. Remember that the reviewer wants to improve the world just as much as you do, only in a slightly different way. If you don't understand some comment, ask the reviewer to clarify. Accept authority when applicable. If you're making changes in an area where you're not the area expert, acknowledge that your reviewers may be. Take their advice seriously, even if it is to not make the change. There are many reasons [why a change may get rejected](#why-is-my-change-rejected). And you did read the section [Things to consider before changing OpenJDK code], right?
@@ -88,7 +88,7 @@ If you have an actual reason to create a PR before the change is all done, make
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.
+ If the set of files in the PR has changed, this may affect the [Groups](https://openjdk.org/bylaws#group) that need to review the PR. Make sure to adjust the PR labels accordingly.
If you want to update the title of the PR, remember that the one and only truth is the JBS issue, so the title must first be changed there.
@@ -96,12 +96,13 @@ If you have an actual reason to create a PR before the change is all done, make
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](#github-actions) 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.
If your PR is targeting some other branch than `master`, make sure to merge the correct upstream branch (the target branch). Verify that your PR doesn't include changes from some other branch (e.g. `master`) that aren't supposed to be there.
+ 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](#github-actions) that's done automatically by [GitHub](https://github.com) 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.org/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.org/display/SKARA/Pull+Request+Commands#PullRequestCommands-/sponsor) in the PR as well in order for your change to be allowed to be integrated.
+ 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.org/display/SKARA/Pull+Request+Commands#PullRequestCommands-/integrate) in a comment on the PR. If you are not yet a [Committer](https://openjdk.org/bylaws#committer) in the [Project](https://openjdk.org/bylaws#project), ask your [Sponsor](https://openjdk.org/bylaws#sponsor) to enter the command [`/sponsor`](https://wiki.openjdk.org/display/SKARA/Pull+Request+Commands#PullRequestCommands-/sponsor) in the PR as well in order for your change to be allowed to be integrated.
#. **After integration**
@@ -116,17 +117,17 @@ If you have an actual reason to create a PR before the change is all done, make
* [Webrev Mailing List](https://mail.openjdk.org/pipermail/webrev-dev/)
:::
-As all OpenJDK projects are hosted on GitHub, most code reviews takes place there. When you publish a PR to an OpenJDK repository the corresponding JBS issue will get a link to the code review in the PR, making this the natural place to go for review. OpenJDK do however provide other tools and infrastructure for code reviews as well: The **webrevs**.
+As all [OpenJDK Projects](https://openjdk.org/bylaws#project) are hosted on [GitHub](https://github.com), most code reviews takes place there. When you publish a PR to an OpenJDK repository the corresponding JBS issue will get a link to the code review in the PR, making this the natural place to go for review. OpenJDK do however provide other tools and infrastructure for code reviews as well: The **webrevs**.
-Webrev refers to both the tool used to create them and its output. The script, [`webrev.ksh`](https://github.com/openjdk/webrev/blob/master/webrev.ksh), is maintained in the [Code Tools](../projects/code-tools) project. Please note that this version of webrev is for use with mercurial and won't work with the git based repositories. You don't actually need tools like this anymore unless you want to host code reviews in other locations than GitHub.
+Webrev refers to both the tool used to create them and its output. The script, [`webrev.ksh`](https://github.com/openjdk/webrev/blob/master/webrev.ksh), is maintained in the [Code Tools Project](../projects/code-tools). Please note that this version of webrev is for use with mercurial and won't work with the git based repositories. You don't actually need tools like this anymore unless you want to host code reviews in other locations than [GitHub](https://github.com).
-On the GitHub reviews you will find links to webrevs. These are automatically generated by the bot and are provided as a complement for those who prefer this style of code review. Many OpenJDK developers are used to the webrevs as this was the default way to provide code for review before OpenJDK moved to GitHub. Though webrevs are mainly deprecated today, they used to be a central part of OpenJDK development and you may still see people use the word as a synonym for code review, so they do deserve to be mentioned here as well.
+On the GitHub reviews you will find links to webrevs. These are automatically generated by the bot and are provided as a complement for those who prefer this style of code review. Many OpenJDK developers are used to the webrevs as this was the default way to provide code for review before OpenJDK moved to [GitHub](https://github.com). Though webrevs are mainly deprecated today, they used to be a central part of OpenJDK development and you may still see people use the word as a synonym for code review, so they do deserve to be mentioned here as well.
## File storage for OpenJDK artifacts - `cr.openjdk.org`
-The `cr.openjdk.org` server provides storage and display of code review materials such as webrevs and other artifacts related to the OpenJDK Community. This area can also be used to store design documents and other documentation related OpenJDK but not related to any specific project that have an OpenJDK wiki space for such purposes.
+The `cr.openjdk.org` server provides storage and display of code review materials such as webrevs and other artifacts related to the OpenJDK Community. This area can also be used to store design documents and other documentation related OpenJDK but not related to any specific [Project](https://openjdk.org/bylaws#project) that have an OpenJDK wiki space for such purposes.
-Any OpenJDK Author can publish materials on the `cr.openjdk.org` server. Users can upload files to temporary storage using secure methods (`rsync`, `scp`, and `sftp`).
+Any OpenJDK [Author](https://openjdk.org/bylaws#author) can publish materials on the `cr.openjdk.org` server. Users can upload files to temporary storage using secure methods (`rsync`, `scp`, and `sftp`).
This site is for open source materials related to the OpenJDK Community only. Users uploading inappropriate materials will lose access and the material will be deleted. Please review the [Terms of Use](https://openjdk.org/legal/terms.html) before using this server.
diff --git a/src/guidestyle.css b/src/guidestyle.css
index 5251c3e..cf6e530 100644
--- a/src/guidestyle.css
+++ b/src/guidestyle.css
@@ -1,3 +1,51 @@
+/* Info boxes */
+.box {
+ margin: 1em 0em;
+ padding: 0 0 .5em .5em;
+ background: #f4f8ff;
+ border-left: 5px solid #437291;
+}
+
+/* Headers in boxes */
+.boxheader {
+ font-weight: bold;
+ padding-top: 0px;
+ margin-bottom: .5em;
+ color: #437291;
+}
+
+/* Notes */
+.note {
+ background-color: #f4f8ff;
+ border-width: 2px;
+ border-color: #437291;
+ border-style: solid none;
+ margin: 1em;
+ padding: 1em 1em 0em 1em;
+}
+
+/* JBS field names */
+.jbs-field {
+ font-weight: bold;
+ color: #333;
+}
+
+/* JBS field values */
+.jbs-value {
+ font-weight: bold;
+ color: #013;
+}
+
+/* JBS labels */
+.jbs-label {
+ font-family: monospace;
+ font-weight: bold;
+ color: #060;
+ white-space: nowrap;
+}
+
+/* Styles below this line are not meant for specific keywords. */
+
div.version {
text-align: right;
font-style: italic;
@@ -49,50 +97,6 @@ pre > code {
margin: 0em;
}
-/* Info boxes */
-.box {
- margin: 1em 0em;
- padding: 0 0 .5em .5em;
- background: #f4f8ff;
- border-left: 5px solid #437291;
-}
-
-.boxheader {
- font-weight: bold;
- padding-top: 0px;
- margin-bottom: .5em;
- color: #437291;
-}
-
-.note {
- background-color: #f4f8ff;
- border-width: 2px;
- border-color: #437291;
- border-style: solid none;
- margin: 1em;
- padding: 1em 1em 0em 1em;
-}
-
-/* JBS field names */
-.jbs-field {
- font-weight: bold;
- color: #333;
-}
-
-/* JBS field values */
-.jbs-value {
- font-weight: bold;
- color: #013;
-}
-
-/* JBS labels */
-.jbs-label {
- font-family: monospace;
- font-weight: bold;
- color: #060;
- white-space: nowrap;
-}
-
table {
border-spacing: 0px;
}