Expand config parameter location explanation (#2518)

* Expand config parameter location explanation

* Further explains how and where shell script parameters should be injected
* Follow on from #2506
* Part 2 of #2129

Signed-off-by: Morgan Davies <[email protected]>
Co-authored-by: Stewart X Addison <[email protected]>

FAQ.md

@@ -63,12 +63,25 @@ All machines at AdoptOpenJDK are set up using the ansible playbooks from the
 
 ## How do I change the parameters, such as configure flags, for a Jenkins build
 
-Either:
-
-- Modify the environment files in [platform-specific-configurations](https://github.com/AdoptOpenJDK/openjdk-build/tree/master/build-farm/platform-specific-configurations)
-- Modify the [pipeline files](https://github.com/AdoptOpenJDK/ci-jenkins-pipelines/tree/master/pipelines/build), although this is normally only done for configuration differences such as OpenJ9 Large Heap builds. Please only do this if the changes you wish to make will effect the Jenkins builds.
-
-[Example PR - Adding a new configure flag for OpenJ9](https://github.com/AdoptOpenJDK/openjdk-build/pull/1442/files)
+Where you change them depends on the scope of the parameter or flag:
+
+- *If the parameter will affect all users, regardless of environment or OS/Arch*
+  - [build.sh](https://github.com/AdoptOpenJDK/openjdk-build/blob/master/sbin/build.sh) OR [makejdk-any-platform.sh](https://github.com/AdoptOpenJDK/openjdk-build/blob/master/makejdk-any-platform.sh) depending on how high up in the execution stack it needs to be.
+  - [Example PR - Adding a new archival feature for OpenJ9 memory dumps](https://github.com/AdoptOpenJDK/openjdk-build/pull/2464)
+- *If the parameter will affect all machines of a specific OS OR related to the environment set up by [our ansible scripts](https://github.com/AdoptOpenJDK/openjdk-infrastructure) at the shell script level*
+  - Modify the relevant environment files in [platform-specific-configurations](https://github.com/AdoptOpenJDK/openjdk-build/tree/master/build-farm/platform-specific-configurations)
+  - [Example PR - Adding a new configure flag for OpenJ9 on all AIX machines](https://github.com/AdoptOpenJDK/openjdk-build/pull/1442/files)
+- *If the parameter will affect only our jenkins environment or jenkins machine environment*
+  - Modify the [pipeline files](https://github.com/AdoptOpenJDK/ci-jenkins-pipelines/tree/master/pipelines/build), although this is normally only done for configuration differences such as OpenJ9 Large Heap builds. See [the configuration file documentation](https://github.com/AdoptOpenJDK/ci-jenkins-pipelines#configuration-files) for more information about adding or altering custom jenkins param.
+  - [Example PR - Adding Jenkins Support for a Cross Compiled Bisheng Binary](https://github.com/AdoptOpenJDK/ci-jenkins-pipelines/pull/68)
+
+### TL;DR (Quick Reference Table)
+
+| Parameter Location | Impact |
+| --- | --- |
+| [build.sh](https://github.com/AdoptOpenJDK/openjdk-build/blob/master/sbin/build.sh) OR [makejdk-any-platform.sh](https://github.com/AdoptOpenJDK/openjdk-build/blob/master/makejdk-any-platform.sh) | Anyone (including end users) who are running [makejdk-any-platform.sh](https://github.com/AdoptOpenJDK/openjdk-build/blob/master/makejdk-any-platform.sh) |
+| [platform-specific-configurations](https://github.com/AdoptOpenJDK/openjdk-build/tree/master/build-farm/platform-specific-configurations) scripts | Those using [build-farm/make-adopt-build-farm.sh](https://github.com/AdoptOpenJDK/openjdk-build/blob/master/build-farm/make-adopt-build-farm.sh) (inc. our pipelines) - should be stuff specific to our machines |
+| Jenkins resources in [ci-jenkins-pipelines](https://github.com/AdoptOpenJDK/ci-jenkins-pipelines) | Only when run through our jenkins pipelines. See the [configuration file documentation](https://github.com/AdoptOpenJDK/ci-jenkins-pipelines#configuration-files) for more information |
 
 ## How to do a new release build
 
@@ -89,4 +102,4 @@ Runtime platforms are in our [supported platforms page](https://adoptopenjdk.net
 
 ## How to add a new build pipeline param and associated job configuration?
 
-[This PR](https://github.com/AdoptOpenJDK/openjdk-build/pull/2416) demonstrates changes required to add a new build pipeline param, and also associated version/platform job configurations for setting the value when needed.
+[This PR](https://github.com/AdoptOpenJDK/openjdk-build/pull/2416) demonstrates changes required to add a new build pipeline param and the associated version/platform job configurations for setting the value when needed  (note, the `pipelines/` dir has since been moved to our [jenkins repository](https://github.com/AdoptOpenJDK/ci-jenkins-pipelines)).