Add support for forks

README.md

@@ -13,8 +13,8 @@ You can see the published documentation at https://terraform-ibm-modules.github.
 - Contributing modules
     - [Local development setup](https://terraform-ibm-modules.github.io/documentation/#/local-dev-setup.md)
     - [Regular developer tasks](https://terraform-ibm-modules.github.io/documentation/#/dev-maintenance.md)
-    - [Contributing a module](https://terraform-ibm-modules.github.io/documentation/#/contribute-module.md)
-    - [Updating an older module ](https://terraform-ibm-modules.github.io/documentation/#/migrate-module.md)
+    - [Contributing modules](https://terraform-ibm-modules.github.io/documentation/#/contribute-module.md)
+    - [Porting an older module ](https://terraform-ibm-modules.github.io/documentation/#/migrate-module.md)
     - [Validation tests](https://terraform-ibm-modules.github.io/documentation/#/tests.md)
     - [GitHub Actions workflows](https://terraform-ibm-modules.github.io/documentation/#/gh-actions.md)
 - [Adding your module to IBM Cloud](https://terraform-ibm-modules.github.io/documentation/#/onboard-ibm-cloud.md)

docs/_sidebar.md

@@ -3,8 +3,8 @@
 - Contributing modules
     - [Local development setup](local-dev-setup.md)
     - [Regular developer tasks](dev-maintenance.md)
-    - [Contributing a module](contribute-module.md)
-    - [Updating an older module ](migrate-module.md)
+    - [Contributing modules](contribute-module.md)
+    - [Porting an older module ](migrate-module.md)
     - [Validation tests](tests.md)
     - [GitHub Actions workflows](gh-actions.md)
 - [Adding your module to IBM Cloud](onboard-ibm-cloud.md)

docs/contribute-module.md

@@ -1,22 +1,28 @@
 # Contributing to the IBM Cloud Terraform modules project
 
-To create a module, you start from the module template. To update a module, you create a branch off the dev branch of the module you want to work with. Then, modify the Terraform logic, create examples, and run tests.
+To create a module, you request a repo, and then fork the repo. To update a module, you fork the repo that you want to work with. Then you modify the Terraform logic, create examples, and run tests.
 
 The process to create a module has several goals.
 
 - To maintain the quality of IBM Cloud Terraform modules.
 - To fix problems that are important to users.
 - To engage the community in working toward the best Terraform modules for IBM Cloud.
 
-Follow these steps to create or update a module.
+## Overall process
+
+Follow these steps to contribute or update a module.
+
+1.  Make sure that you [satisfy the prerequisites](#before-you-begin)
+1.  New repo: [Request a repo](#request-a-repo).
+1.  [Fork and clone the repo](#fork-clone-and-initialize-the-repo).
+1.  [Add the dependencies](#add-the-dependencies) in the repo.
+1.  [Make your code changes](#update-the-terraform-files).
+1.  [Test your changes](#create-or-update-examples) with example code and tests.
+1.  [Open a pull request](#push-your-code-and-submit-for-review).
 
 ## Before you begin
 
-- If you're running Microsoft Windows, set up Windows Subsystem for Linux [WSL](https://ubuntu.com/wsl) and run commands within WSL.
-- Make sure that you have a current version of Python 3 and pip. 
-    - To check your installed python version, run `python3 --version`.
-    - To check whether "pip" is installed, run `python3 -m pip --version`.
-- Make sure that you have a recent stable version of [Go](https://go.dev/doc/install) installed and available in your PATH environment variable.
+[inc-prereqs-dev.md](inc-prereqs-dev.md ':include')
 
 ## Request a repo
 
@@ -28,11 +34,11 @@ Submit a request for a new module repo in the [terraform-ibm-issue-tracker](http
 
 When your repo is created, return to this topic and continue the steps.
 
-## Clone and initialize the repo
+## Fork, clone, and initialize the repo
 
-Clone either the repo that you just created or the module repo that you want to update.
+Fork either the repo that was just created or the module repo that you want to update.
 
-[inc-clone.md](inc-clone.md ':include')
+[inc-fork.md](inc-fork.md ':include')
 
 ## Add the dependencies
 
@@ -44,58 +50,21 @@ Clone either the repo that you just created or the module repo that you want to
 
 ## Update the Terraform files
 
-1.  From the root of the newly cloned repo, create a branch to work in by running the command `git checkout -b ＜YOUR_TOPIC_BRANCH>`. Replace `＜YOUR_TOPIC_BRANCH>` with your own branch name.
-1.  Implement (or update) the logic for your module by updating the `main.tf`, `version.tf`, `variables.tf`, and `outputs.tf` Terraform files.
-
-    - For more information about module structure and guidance, see [Authoring guidelines](implementation-guidelines.md).
-    - For more information about Terraform for IBM Cloud, see [Creating Terraform on IBM Cloud templates](https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-create-tf-config) in the IBM Cloud docs.
-
+[inc-tf-update.md](inc-tf-update.md ':include')
 ## Create or update examples
 
 Create or update at least one end-to-end example to test your code changes.
 
 1.  Implement (or update) the logic for your module examples by updating the `main.tf`, `version.tf`, `variables.tf`, and `version.tf` Terraform files in the `examples/default` directory.
 1.  Update the `README.md` file in the same examples directory to provide some basic information about what the example does.
 
+### About end-to-end examples
+
 [inc-examples](inc-examples.md ':include')
 
 ## Run examples and clean up
 
-Run your examples to test the logic. After the examples run, destroy the resources.
-
-1.  Set the environment variables that the test uses.
-
-    1.  Set the `ibmcloud_api_key` variable as an environment variable.
-
-        ```bash
-        export TF_VAR_ibmcloud_api_key=<YOUR_API_KEY>
-        ```
-
-        Replace `<YOUR_API_KEY>` with the value of the API key that you want to use to test the code.
-
-1.  In the `examples/default` directory, initialize the module to pull the dependencies.
-
-    ```bash
-    terraform init
-    ```
-
-1.  Apply the configuration and run the example.
-
-    ```bash
-    terraform apply
-    ```
-
-    Confirm that you want Terraform to apply the changes by typing `yes`. If everything runs successfully, you validated your Terraform logic.
-
-1.  Clean up.
-
-    1.  Run the following command to remove the resources that the example created.
-
-        ```bash
-        terraform destroy
-        ```
-
-    1.  Confirm that you want Terraform the destroy the resources by typing `yes`.
+[inc-examples-run](inc-examples-run.md ':include')
 
 ## Update the PR tests
 
@@ -109,50 +78,40 @@ Now that you tested the module by running your examples directly, update the `pr
 
 For more information about testing modules in this project, see [Tests](tests.md).
 
-## Commit your code and submit for review
+## Push your code and submit for review
 
 After your PR tests pass, create a pull request.
 
-When the PR is merged, your commit messages might change because the merging team uses the [squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-pull-request-commits) option to merge PRs. The PR commit message that's included by the merging team determines whether a new version of a module is needed and which [semantic versioning number](versioning.md) to use. The message also is published in the release notes for the module.
+### Verify changes
 
-1.  Locally merge (or rebase) the upstream `main` branch into your topic branch:
+[inc-precommit](inc-precommit.md ':include')
 
-    ```bash
-    git pull [--rebase] upstream main
-    ```
-1.  Run the pre-commit hooks from the root of the repo to identify other changes that you need to make:
-
-    ```bash
-    pre-commit run --all-files
-    ```
-
-1.  Iteratively address all the issues from this check, commit the changes, and run the `pre-commit` command until all tests pass. For example, commit changes to the readme file that is updated from the pre-commit hooks.
-1.  Push your topic branch to your repo:
-
-    ```bash
-    git push origin ＜YOUR_TOPIC_BRANCH>
-    ```
+### Open a pull request
 
 1.  Open a pull request:
 
     1.  Start by contributing a draft PR. A draft pull request provides insight about the work that you're doing but cannot be merged. To create a draft pull request, use the drop-down and select **Create Draft Pull Request**, then click **Draft Pull Request**.
-        - Open your PR from your branch to `main`.
+        - Open your PR from your working branch to `main`.
         - Provide a clear title and description. Be sure to merge the latest changes from upstream before you create the PR.
     1.  When you're ready to merge your code, mark your draft pull request as ready for review. For more information, see [Changing the stage of a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request).
-    1.  Run the CI pipeline workflow by adding a comment to the PR with the following text:
+    1.  If you are in the `github-collaborators` team, you can run CI pipeline workflow by adding a comment to the pull request with the following text:
 
         ```text
         /run pipeline
         ```
 
+      ?> **Retriction:** If the CI pipeline workflow doesn't run when you post the comment, you don't have access to run the pipeline. The merging team will run the workflow for you.
+
         For more information about workflows, see [GitHub Actions workflows](gh-actions.md).
 
+When the PR is merged, your commit messages might change because the merging team uses the [squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-pull-request-commits) option to merge PRs. The PR commit message that's included by the merging team determines whether a new version of a module is needed and which [semantic versioning number](versioning.md) to use. The message also is published in the release notes for the module.
+
 !> **Important** By contributing content, you agree to allow the project owner to license your work under the same license as that used by the project.
 
 ## Next steps
 
 After the initial merge of a new repo, enable the upgrade test in `tests/pr_test.go`.
 
-When you create a repo from the module template, the upgrade test is disabled by default. You can't run an upgrade test until the initial module code is merged to the main branch.
+When a module is created for you from the module template, the upgrade test is disabled by default. That's because you can't run an upgrade test until the initial module code is merged to the main branch.
 
-Create a pull request to enable the upgrade test in `pr_test.go` by commenting out the line that starts with `t.Skip`.
+1.  Create a pull request to enable the upgrade test in `pr_test.go` by commenting out the line that starts with `t.Skip`.

docs/gh-actions.md

@@ -9,7 +9,7 @@ The following reusable workflows are included in the [terraform-ibm-module-templ
     - Called from `/.github/workflows/ci.yml`.
     - If you are in the `github-collaborators` team, you can run this workflow by adding a comment to the pull request with the following text:
 
-        ```
+        ```text
         /run pipeline
         ```
 

docs/implementation-guidelines.md

@@ -43,7 +43,7 @@ If this module is published as a deployable architecture in IBM Cloud, include a
 - Start from the [Markdown template](https://github.ibm.com/allen-dean/tim-docs/raw/main/docs/templates/reference-architecture-template.md ':target=_blank') to guide you.
 - Include an architecture diagram.
 - Save the files in your module in the `reference-architectures` directory.
-- For more information, see the template in the [terraform-ibm-module-template](https://github.com/terraform-ibm-modules/terraform-ibm-module-template/blob/main/reference-architectures/reference-architecture-template.md).
+- For more information, see the template in the [documentation](https://github.com/terraform-ibm-modules/documentation/blob/main/docs/templates/reference-architecture-template.md) repo.
 
 ## Module examples
 

docs/inc-examples-run.md

@@ -0,0 +1,33 @@
+Run your examples to test the logic. After the examples run, destroy the resources.
+
+1.  Set the `ibmcloud_api_key` environment variable that the test uses.
+
+    ```bash
+    export TF_VAR_ibmcloud_api_key=<YOUR_API_KEY>
+    ```
+
+    Replace `<YOUR_API_KEY>` with the value of the API key that you want to use to test the code.
+
+1.  In the `examples/default` directory, initialize the module to pull the dependencies.
+
+    ```bash
+    terraform init
+    ```
+
+1.  Apply the configuration and run the example.
+
+    ```bash
+    terraform apply
+    ```
+
+    Confirm that you want Terraform to apply the changes by typing `yes`. If everything runs successfully, you validated your Terraform logic.
+
+1.  Clean up.
+
+    1.  Run the following command to remove the resources that the example created.
+
+        ```bash
+        terraform destroy
+        ```
+
+    1.  Confirm that you want Terraform the destroy the resources by typing `yes`.

docs/inc-fork.md

@@ -0,0 +1,39 @@
+1.  Navigate to the repository that you want to update.
+1.  Fork the repo by clicking **Fork** in the top-right corner of the page.
+
+    If you plan to create another module from this code, type a new repository name.
+1.  Clone your fork:
+
+    - To clone by using SSH, run the following command. You need a valid SSH key for github.com. For more information, see the steps in the [GitHub docs](https://docs.github.com/en/authentication/connecting-to-github-with-ssh).
+
+        ```bash
+        git clone git@github.com:<REPO_OWNER>/<REPO_NAME>.git
+        ```
+
+    - To clone by using HTTPS, run the following command.
+
+        ```bash
+        git clone https://github.ibm.com/<REPO_OWNER>/<REPO_NAME>.git
+        ```
+
+    Where `<REPO_OWNER>` is the owner of the forked repository and `<REPO_NAME>` is the name of the repo you forked.
+1.  Confirm the remote repository for your fork.
+
+    1.  Locally, list the remote repo:
+
+        ```bash
+        git remote -v
+        ```
+
+    1.  If necessary, add or update the upstream repo. For example, if you use SSH, run this command:
+
+        ```bash
+        git remote add upstream git@github.com:terraform-ibm-modules/<REPO_NAME>.git
+        ```
+
+    For more information, see [Configuring a remote repository for a fork](https://docs.github.com/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork?platform=mac).
+1.  Initialize the Git submodule:
+
+    ```bash
+    git submodule update --init
+    ```

docs/inc-precommit.md

@@ -0,0 +1,17 @@
+1.  Locally merge (or rebase) the upstream `main` branch into your topic branch:
+
+    ```bash
+    git pull [--rebase] upstream main
+    ```
+1.  Run the pre-commit hooks from the root of the repo to identify other changes that you need to make:
+
+    ```bash
+    pre-commit run --all-files
+    ```
+
+1.  Iteratively address all the issues from this check, commit the changes, and run the `pre-commit` command until all tests pass. For example, commit changes to the readme file that is updated from the pre-commit hooks.
+1.  Push your topic branch to your repo:
+
+    ```bash
+    git push origin ＜YOUR_TOPIC_BRANCH>
+    ```

docs/inc-prereqs-dev.md

@@ -0,0 +1,5 @@
+- If you're running Microsoft Windows, set up Windows Subsystem for Linux [WSL](https://ubuntu.com/wsl) and run commands within WSL.
+- Make sure that you have a current version of Python 3 and pip.
+    - To check your installed python version, run `python3 --version`.
+    - To check whether "pip" is installed, run `python3 -m pip --version`.
+- Make sure that you have a recent stable version of [Go](https://go.dev/doc/install) installed and available in your PATH environment variable.

docs/inc-tf-update.md

@@ -0,0 +1,5 @@
+1.  From the root of the newly cloned repo, create a branch to work in by running the command `git checkout -b ＜YOUR_TOPIC_BRANCH>`. Replace `＜YOUR_TOPIC_BRANCH>` with your own branch name.
+1.  Implement (or update) the logic for your module by updating the `main.tf`, `version.tf`, `variables.tf`, and `outputs.tf` Terraform files.
+
+    - For more information about module structure and guidance, see [Authoring guidelines](implementation-guidelines.md).
+    - For more information about Terraform for IBM Cloud, see [Creating Terraform on IBM Cloud templates](https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-create-tf-config) in the IBM Cloud docs.

docs/local-dev-setup.md

@@ -1,20 +1,16 @@
 # Local development setup
 
-Follow these steps to set up your local development environment for working with the `terraform-ibm-modules` project.
+Follow these steps to set up your local development environment for working with the `terraform-ibm-modules` project. See [Contributing to the IBM Cloud Terraform modules project](contribute-module.md) for detailed steps about how to create or update a module.
 
 ?> **Tip**: For regular maintenance tasks, see [Regular developer tasks](dev-maintenance.md).
 
 ## Before you begin
 
-- Make sure that you have a current version of Python 3 and pip
-  - To check your installed python version, run `python3 --version`.
-  - To check whether "pip" is installed, run `python3 -m pip --version`.
-- Make sure that a recent stable version of [Go is installed](https://go.dev/doc/install) and available in your PATH environment variable.
-- On Microsoft Windows, set up Windows Subsystem for Linux [WSL](https://ubuntu.com/wsl) and run commands within WSL.
+[inc-prereqs-dev.md](inc-prereqs-dev.md ':include')
 
-## Clone and initialize the repo
+## Fork, clone, and initialize the repo
 
-[inc-clone](inc-clone.md ':include')
+[inc-fork](inc-fork.md ':include')
 
 ## Add the dependencies