Adding a navigational structure based on aip.dev

docs/.gitignore

@@ -1,2 +1,4 @@
 _site/
 Gemfile.lock
+vendor/
+.bundle/

docs/what-is-a-diamond-dependency-conflict.md → docs/0001-what-is-a-diamond-dependency-conflict.md

@@ -1,3 +1,7 @@
+---
+concepts: true
+permalink: /what-is-a-diamond-dependency-conflict
+---
 # What is a diamond dependency conflict?
 
 A diamond dependency conflict is a scenario where two or more
@@ -62,4 +66,4 @@ state of compatibility.
 
 If you want to understand diamond dependency conflicts more deeply, proceed to
 the next article,
-[Why doesn't the compiler catch diamond dependency conflicts?](why-doesnt-the-compiler-catch-diamond-dependency-conficts.md).
+[Why doesn't the compiler catch diamond dependency conflicts?](0002-why-doesnt-the-compiler-catch-diamond-dependency-conficts.md).

docs/why-doesnt-the-compiler-catch-diamond-dependency-conficts.md → docs/0002-why-doesnt-the-compiler-catch-diamond-dependency-conficts.md

@@ -1,9 +1,12 @@
+---
+concepts: true
+permalink: /why-doesnt-the-compiler-catch-diamond-dependency-conficts
+---
 # Why doesn't the compiler catch diamond dependency conflicts?
 
-When first introduced to the problem of [diamond dependency
-conflicts](what-is-a-diamond-dependency-conflict.md), many people ask: "Why
-doesn't the compiler catch it?" To explain why, we need to dive into how the
-Java build process works.
+When first introduced to the problem of [diamond dependency conflicts](0001-what-is-a-diamond-dependency-conflict.md),
+many people ask: "Why doesn't the compiler catch it?" To explain why, we need
+to dive into how the Java build process works.
 
 When `javac` compiles a program, it verifies that every class, variable, or
 other type of symbol referenced by the code can be found somewhere. Let's look

docs/JLBP-1.md → docs/JLBP-0001.md

@@ -1,4 +1,9 @@
-# [JLBP-1] Minimize dependencies
+---
+jlbp:
+  id: JLBP-1
+permalink: /JLBP-1
+---
+# Minimize dependencies
 
 Use the minimum number of dependencies that is reasonable.
 Every dependency of a library is a liability of both

docs/JLBP-2.md → docs/JLBP-0002.md

@@ -1,4 +1,9 @@
-# [JLBP-2] Minimize API surface
+---
+jlbp:
+  id: JLBP-2
+permalink: /JLBP-2
+---
+# Minimize API surface
 
 Avoid exposing types from your dependencies.
 

docs/JLBP-3.md → docs/JLBP-0003.md

@@ -1,4 +1,9 @@
-# [JLBP-3] Use Semantic Versioning
+---
+jlbp:
+  id: JLBP-3
+permalink: /JLBP-3
+---
+# Use Semantic Versioning
 
 Semantic versioning is a convention in which "version numbers and the way they
 change convey meaning about the underlying code and what has been modified from one 

docs/JLBP-4.md → docs/JLBP-0004.md

@@ -1,14 +1,19 @@
-# [JLBP-4] Avoid dependencies on unstable libraries and features
+---
+jlbp:
+  id: JLBP-4
+permalink: /JLBP-4
+---
+# Avoid dependencies on unstable libraries and features
 
 Do not depend on libraries that are pre-1.0 or on unstable features in
 libraries that are 1.0 or later.
 Unstable libraries allow breaking changes to their
 public APIs within the same major version. For libraries following semantic
-versioning, this means libraries with a 0.x.y version. See [JLBP-3](JLBP-3.md)
+versioning, this means libraries with a 0.x.y version. See [JLBP-3](JLBP-0003.md)
 for more details on semantic versioning.
 Unstable features within an otherwise stable library
 are marked with an annotation such as `@Beta`. See
-[JLBP-3](JLBP-3.md) for more details on annotating unstable features.
+[JLBP-3](JLBP-0003.md) for more details on annotating unstable features.
 
 If your library depends on an unstable library or feature which
 experiences a breaking change between versions, your library is locked to

docs/JLBP-5.md → docs/JLBP-0005.md

@@ -1,4 +1,9 @@
-# [JLBP-5] Avoid dependencies that overlap classes with other dependencies
+---
+jlbp:
+  id: JLBP-5
+permalink: /JLBP-5
+---
+# Avoid dependencies that overlap classes with other dependencies
 
 Definition: When the same fully qualified class name is provided by
   two or more distinct artifacts (different group IDs, different

docs/JLBP-6.md → docs/JLBP-0006.md

@@ -1,4 +1,9 @@
-# [JLBP-6] Rename artifacts and packages together
+---
+jlbp:
+  id: JLBP-6
+permalink: /JLBP-6
+---
+# Rename artifacts and packages together
 
 When a library B in Java depends on another library A through the Maven
 repository system, library B needs two identifiers to find classes in library A:
@@ -45,7 +50,7 @@ Recommendations:
 - Whether or not you make breaking changes, don't publish
   the same classes under multiple Maven IDs; this creates a situation where
   artifacts have "overlapping classes." Another best practice,
-  [JLBP-5](JLBP-5.md), covers how consumers need to handle such problematic
+  [JLBP-5](JLBP-0005.md), covers how consumers need to handle such problematic
   scenarios — don't create new cases!
 
   - Corollary 1: Once you have published under a particular Maven ID, you are

docs/JLBP-7.md → docs/JLBP-0007.md

@@ -1,7 +1,12 @@
-# [JLBP-7] Make breaking transitions easy
+---
+jlbp:
+  id: JLBP-7
+permalink: /JLBP-7
+---
+# Make breaking transitions easy
 
 When a library makes an in-place breaking change (meaning that the Java package
-is not renamed - see [JLBP-6](JLBP-6.md) for more discussion on renaming rules),
+is not renamed - see [JLBP-6](JLBP-0006.md) for more discussion on renaming rules),
 this can create a lot of work for consumers to adapt to the change. If a change
 is "atomic" (meaning that the old version of something like a method is removed
 at the same time the new version is added), all usages of the old method must be

docs/JLBP-8.md → docs/JLBP-0008.md

@@ -1,18 +1,23 @@
-# [JLBP-8] Advance widely used functionality to a stable version
+---
+jlbp:
+  id: JLBP-8
+permalink: /JLBP-8
+---
+# Advance widely used functionality to a stable version
 
 Libraries at 0.x versions and unstable features (which should be marked with
 annotations if they live in a stable library, as outlined in
-[JLBP-3](JLBP-3.md)) make no promises about stability. If they become widely
+[JLBP-3](JLBP-0003.md)) make no promises about stability. If they become widely
 used, they can cause problems when there are surface breakages (which is allowed
-per the rules of unstable functionality, explained in [JLBP-3](JLBP-3.md)). If
+per the rules of unstable functionality, explained in [JLBP-3](JLBP-0003.md)). If
 such breakages can cause widespread pain, the unstable features can become
 de facto GA. Promote widely-used unstable libraries and features to 1.0 
 and commit to thier APIs, even if the functionality is not complete.
 Stability is not about completeness but about guarantees not to break
 users' code frequently.
 
 If the surface needs to change before it stabilizes, follow the process in
-[JLBP-7](JLBP-7.md) to minimize disruption to the ecosystem. (TL;DR: Mark the old
+[JLBP-7](JLBP-0007.md) to minimize disruption to the ecosystem. (TL;DR: Mark the old
 surface `@Deprecated` and add the new surface in phase 1, delete the old surface
 in phase 2). However, if it would take a long time for the ecosystem to complete
 phase 2 (remove all references to the old surface), consider promoting the

docs/JLBP-9.md → docs/JLBP-0009.md

@@ -1,4 +1,9 @@
-# [JLBP-9] Support the minimum Java version of your consumers
+---
+jlbp:
+  id: JLBP-9
+permalink: /JLBP-9
+---
+# Support the minimum Java version of your consumers
 
 Imagine that library B depends on library A and both work with Java 8.
 If library A releases a new version that requires Java 11, library B cannot upgrade

docs/JLBP-10.md → docs/JLBP-0010.md

@@ -1,4 +1,9 @@
-# [JLBP-10] Maintain API stability as long as needed for consumers
+---
+jlbp:
+  id: JLBP-10
+permalink: /JLBP-10
+---
+# Maintain API stability as long as needed for consumers
 
 Every breaking change that consumers must incorporate into their own code incurs
 a cost to them. There is the immediate cost of the consumers who are forced to

docs/JLBP-11.md → docs/JLBP-0011.md

@@ -1,4 +1,9 @@
-# [JLBP-11] Keep dependencies up to date
+---
+jlbp:
+  id: JLBP-11
+permalink: /JLBP-11
+---
+# Keep dependencies up to date
 
 Release no later than 6 weeks after any of your dependencies
 releases a higher version. Time is important, not just how many versions behind,

docs/JLBP-12.md → docs/JLBP-0012.md

@@ -1,4 +1,9 @@
-# [JLBP-12] Make level of support and API stability clear
+---
+jlbp:
+  id: JLBP-12
+permalink: /JLBP-12
+---
+# Make level of support and API stability clear
 
 Document the lifecycle status and corresponding level of support
 of the library. Examples include:

docs/JLBP-13.md → docs/JLBP-0013.md

@@ -1,4 +1,9 @@
-# [JLBP-13] Quickly remove references to deprecated features in dependencies
+---
+jlbp:
+  id: JLBP-13
+permalink: /JLBP-13
+---
+# Quickly remove references to deprecated features in dependencies
 
 The earlier you remove usages of external deprecated functionality, the
 more versions of your product will work with your dependency once the

docs/JLBP-14.md → docs/JLBP-0014.md

@@ -1,4 +1,9 @@
-# [JLBP-14] Specify a single, overridable version of each dependency
+---
+jlbp:
+  id: JLBP-14
+permalink: /JLBP-14
+---
+# Specify a single, overridable version of each dependency
 
 Give the version of each dependency as a single value such as `2.3`.
 Do not use a Maven range such as `[2.3,2.9]`, `[2.3,)`, or even `[2.3]`.

docs/JLBP-15.md → docs/JLBP-0015.md

@@ -1,4 +1,9 @@
-# [JLBP-15] Publish a BOM for multi-module projects
+---
+jlbp:
+  id: JLBP-15
+permalink: /JLBP-15
+---
+# Publish a BOM for multi-module projects
 
 A [BOM](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html)
 enables consumers of a library to select

docs/JLBP-16.md → docs/JLBP-0016.md

@@ -1,7 +1,12 @@
-# [JLBP-16] Ensure upper version alignment of dependencies for consumers
+---
+jlbp:
+  id: JLBP-16
+permalink: /JLBP-16
+---
+# Ensure upper version alignment of dependencies for consumers
 
 For multi-module projects, this best practice assumes you have already applied
-[JLBP-15](JLBP-15.md), so that your project has a BOM.
+[JLBP-15](JLBP-0015.md), so that your project has a BOM.
 
 Upper version alignment is defined in the [glossary](glossary.md).
 

docs/JLBP-17.md → docs/JLBP-0017.md

@@ -1,4 +1,9 @@
-# [JLBP-17] Coordinate rollout of breaking changes
+---
+jlbp:
+  id: JLBP-17
+permalink: /JLBP-17
+---
+# Coordinate rollout of breaking changes
 
 When a library introduces a breaking change, consumers
 can't update to that version until all their other dependencies which also use
@@ -10,8 +15,7 @@ Perform the rollout in this manner:
 
 1. Decide whether to introduce the incompatibility in a single release or
    make the change in two phases.
-   - The two-phase approach is described in [JLBP-7: Make breaking transitions
-     easy](JLBP-7.md).
+   - The two-phase approach is described in [JLBP-7: Make breaking transitions easy](JLBP-0007.md).
    - If the feature is used by stable code in other libraries, you must use the
      two-phase approach, except for the types of changes where this is
      impossible (see below).
@@ -36,7 +40,7 @@ Perform the rollout in this manner:
    - To use the two-phase approach, mark the undesired surface as
      `@Deprecated` and release. Make sure that all consuming libraries
      have removed their references to the deprecated functionality. This invokes
-     [JLBP-13](JLBP-13.md) for consuming libraries.
+     [JLBP-13](JLBP-0013.md) for consuming libraries.
 
 3. Release the incompatible version and make sure that the version propagates up
    the dependency tree as quickly as possible. In the case of in-place breakage,

docs/JLBP-18.md → docs/JLBP-0018.md

@@ -1,4 +1,9 @@
-# [JLBP-18] Only shade dependencies as a last resort
+---
+jlbp:
+  id: JLBP-18
+permalink: /JLBP-18
+---
+# Only shade dependencies as a last resort
 
 Shading is a process where a dependency is relocated to a different Java package
 and copied into the same jar as the code that relies on that dependency.
@@ -26,7 +31,7 @@ There are a number of problems with shading:
   of some constants.
 - It is easy to accidentally fail to relocate classes or other files, resulting in
   an artifact that overlaps classes and files with the original dependency
-  (creating the situation described in [JLBP-5](JLBP-5.md)).
+  (creating the situation described in [JLBP-5](JLBP-0005.md)).
 - Shading violates many closed source licenses. If the license contains
   language such as "You must not reverse engineer, decompile, disassemble,
   modify, or translate the Software", you should consult an attorney before 

docs/JLBP-19.md → docs/JLBP-0019.md

@@ -1,4 +1,9 @@
-# [JLBP-19] Place each package in only one module
+---
+jlbp:
+  id: JLBP-19
+permalink: /JLBP-19
+---
+# Place each package in only one module
 
 All classes from the same Java package must be in one and only
 one JAR file in the classpath.

docs/JLBP-20.md → docs/JLBP-0020.md

@@ -1,4 +1,9 @@
-# [JLBP-20] Give each jar a module name
+---
+jlbp:
+  id: JLBP-20
+permalink: /JLBP-20
+---
+# Give each jar a module name
 
 For compatibility with the Java Platform Module System (JPMS) in Java 9 and
 later, every JAR you publish should have a module name, even if the library

docs/README.md

@@ -1,6 +1,8 @@
 ---
-page.title: Google Best Practices for Java Libraries
+page:
+  title: Google Best Practices for Java Libraries
 permalink: /
+exclude_from_search: true
 ---
 
 # Google Best Practices for Java Libraries
@@ -14,32 +16,18 @@ Java libraries with fewer dependency conflicts and other kinds of problems. The
 list is open-ended, so new ones may be added from time to time.
 
 ## Best practices
-- [JLBP-1](JLBP-1.md): Minimize dependencies
-- [JLBP-2](JLBP-2.md): Minimize API surface
-- [JLBP-3](JLBP-3.md): Use semantic versioning
-- [JLBP-4](JLBP-4.md): Avoid dependencies on unstable libraries and features
-- [JLBP-5](JLBP-5.md): Avoid dependencies that overlap classes with other
-  dependencies
-- [JLBP-6](JLBP-6.md): Rename artifacts and packages together
-- [JLBP-7](JLBP-7.md): Make breaking transitions easy
-- [JLBP-8](JLBP-8.md): Advance widely used functionality to a stable version
-- [JLBP-9](JLBP-9.md): Support the minimum Java version of your consumers
-- [JLBP-10](JLBP-10.md): Maintain API stability as long as needed for consumers
-- [JLBP-11](JLBP-11.md): Keep dependencies up to date
-- [JLBP-12](JLBP-12.md): Make level of support and API stability clear
-- [JLBP-13](JLBP-13.md): Quickly remove references to deprecated features in
-   dependencies
-- [JLBP-14](JLBP-14.md): Specify a single, overridable version of each dependency
-- [JLBP-15](JLBP-15.md): Produce a BOM for multi-module projects
-- [JLBP-16](JLBP-16.md): Ensure upper version alignment of dependencies for
-  consumers
-- [JLBP-17](JLBP-17.md): Coordinate rollout of breaking changes
-- [JLBP-18](JLBP-18.md): Only shade dependencies as a last resort
-- [JLBP-19](JLBP-19.md): Place each package in only one module
-- [JLBP-20](JLBP-20.md): Give each jar a module name
-
-## Introductory material and reference
-- [What is a diamond dependency conflict?](what-is-a-diamond-dependency-conflict.md)
-- [Why doesn't the compiler catch diamond dependency conflicts?](why-doesnt-the-compiler-catch-diamond-dependency-conficts.md)
+
+{% for p in site.pages %}{% if p.jlbp -%}
+- [{{ p.jlbp.id }}]({{ p.url | relative_url }}): {{ p.title }}
+{% endif %}{% endfor -%}
+
+## Concepts
+
+{% for p in site.pages %}{% if p.concepts -%}
+- [{{ p.title}}]({{ p.url | relative_url }})
+{% endif %}{% endfor -%}
+
+## Reference
+
 - [Glossary](glossary.md): Terms used in the best practices and other places in
   cloud-opensource-java.

docs/_config.yml

@@ -1,3 +1,5 @@
 name: Google Best Practices for Java Libraries
 title: Google Best Practices for Java Libraries
 google_analytics: UA-43239122-3
+github:
+  repository_url: https://github.com/GoogleCloudPlatform/cloud-opensource-java