Document the org structure and index the axes of variability

Author: necto

README.adoc

@@ -5,25 +5,28 @@ An example of a flawed C++ code. The https://github.com/sc-sq-c-family-examples/
 The https://github.com/sc-sq-c-family-examples/code[code repository] is forked into other repositories in https://github.com/sc-sq-c-family-examples[this collection] to add a specific build system, platform, and CI.
 The downstream repositories are analyzed either with https://www.sonarqube.org/[SonarQube] or https://sonarcloud.io/[SonarCloud].
 
-== Forking the code repository
-Since GitHub disallows forking of a repository within the same organization, here is the equivalent in `git` commands (on the example of `linux-cmake-gh-actions`):
-
-Clone the newly created repository:
-----
-git clone gh:sc-sq-c-family-examples/linux-cmake-gh-actions
-cd linux-cmake-gh-actions
-----
-Add the https://github.com/sc-sq-c-family-examples/code[code repository] as a second remote named `code`:
-----
-git remote add code git@github.com:sc-sq-c-family-examples/code
-----
-Get the code:
-----
-git pull code master
-----
-If the contents of the https://github.com/sc-sq-c-family-examples/code[code repository] changes, you can pull the changes with the last command.
-
-Push the changes to the custom repository:
-----
-git push origin master
-----
+You can find examples for:
+* https://github.com/sc-sq-c-family-examples?q=linux[Linux]
+* https://github.com/sc-sq-c-family-examples?q=macos[MacOS]
+* https://github.com/sc-sq-c-family-examples?q=windows[Windows]
+
+Using the following build systems:
+* https://github.com/sc-sq-c-family-examples?q=cmake[CMake]
+* https://github.com/sc-sq-c-family-examples?q=autotools[GNU Autotools]
+* https://github.com/sc-sq-c-family-examples?q=xcode[Xcode]
+* https://github.com/sc-sq-c-family-examples?q=msbuild[MSBuild]
+
+Running on the following CI services:
+* https://github.com/sc-sq-c-family-examples?q=azure[Azure DevOps]
+* https://github.com/sc-sq-c-family-examples?q=gh-actions[GitHub Actions]
+* https://github.com/sc-sq-c-family-examples?q=travis[Travis]
+* https://github.com/sc-sq-c-family-examples?q=jenkins[Jenkins]
+* https://github.com/sc-sq-c-family-examples?q=gitlab[GitLab CI]
+* https://github.com/sc-sq-c-family-examples?q=bitbucket[BitBucket Pipelines]
+
+Configured for analysis on:
+* https://github.com/sc-sq-c-family-examples?q=-sq[SonarQube]
+* https://github.com/sc-sq-c-family-examples?q=-sc[SonarCloud]
+
+
+See link:./examples-structure.adoc[examples-structure.adoc] for a description of the structure of https://github.com/sc-sq-c-family-examples[this GitHub organization] and the relations between its different repositories.

examples-structure.adoc

@@ -0,0 +1,45 @@
+
+= Structure of the Examples Org
+https://github.com/sc-sq-c-family-examples[This GitHub organization] contains a collection of example configurations for different platforms, build systems, and CI services all with one goal: analyze the code on https://www.sonarqube.org/[SonarQube] or https://sonarcloud.io/[SonarCloud].
+
+The repositories form a hierarchy.
+
+* The hierarchy starts from the https://github.com/sc-sq-c-family-examples/code[code-only repository] that contains the flawed code and the common boilerplate files.
+* The second level of hierarchy are OS\build-system repositories, such as https://github.com/sc-sq-c-family-examples/windows-msbuild[windows-msbuild] or https://github.com/sc-sq-c-family-examples/linux-cmake[linux-cmake]. They take the code from the code-only repository as is and add the build configuration files for the corresponding OS and build system.
+* The last level of hierarchy are the CI-enabled repositoroes (for example, https://github.com/sc-sq-c-family-examples/linux-cmake-azure-sc[linux-cmake-azure-sc]). These repositories build upon the repositories with configured builds and add a CI configuration for popular CI services. In the CI config they set up a SonarCloud (repository name ending in `-sc`) or a SonarQube (repository name ending in `-sq`) connection.
+
+Here is an example dependency path: https://github.com/sc-sq-c-family-examples/code[code] -> https://github.com/sc-sq-c-family-examples/linux-cmake[linux-cmake] -> https://github.com/sc-sq-c-family-examples/linux-cmake-azure-sc[linux-cmake-azure-sc].
+
+== Forking the code repository
+Since GitHub disallows forking of a repository within the same organization, here is the equivalent in `git` commands (on the example of `linux-cmake`):
+
+Clone the newly created repository:
+----
+git clone gh:sc-sq-c-family-examples/linux-cmake
+cd linux-cmake
+----
+Add the https://github.com/sc-sq-c-family-examples/code[code repository] as a second remote named `code`:
+----
+git remote add code git@github.com:sc-sq-c-family-examples/code
+----
+Get the code:
+----
+git pull code main
+----
+If the contents of the https://github.com/sc-sq-c-family-examples/code[code repository] changes, you can pull the changes with the last command.
+
+Push the changes to the custom repository:
+----
+git push origin main
+----
+
+This will enable the flow of changes from the https://github.com/sc-sq-c-family-examples/code[code] repository to the https://github.com/sc-sq-c-family-examples/linux-cmake[linux-cmake] repository (the first arrow in the example above).
+
+To make the changes flow further to the https://github.com/sc-sq-c-family-examples/linux-cmake-azure-sc[linux-cmake-azure-sc] repository:
+----
+git clone gh:sc-sq-c-family-examples/linux-cmake-azure-sc
+cd linux-cmake-azure-sc
+git remote add code git@github.com:sc-sq-c-family-examples/linux-cmake
+git pull code main
+git push origin main
+----