Skip to main contentIBM Cloud Pak Playbook

Contributing to the Cloud Pak Playbook

Anyone can contribute to the IBM Cloud Paks Playbook, whether you are an IBM’er or not. We welcome your collaboration and contributions happily, as our reference applications are meant to reflect your real world scenarios. There are multiple ways to contribute: report bugs and improvement suggestions, improve documentation, and contribute code.

Bug reports, documentation changes, and feature requests

If you would like to contribute your experience back to the project in the form of encountered bug reports, necessary documentation changes, or new feature requests, this can be done through the use of the repository’s Issues list.

Before opening a new issue, please reference the existing list to make sure a similar or duplicate item does not already exist.
Otherwise, please be as explicit as possible when creating the new item and be sure to include the following:

Bug Reports

  • Specific Project Version
  • Deployment environment
  • A minimal, but complete, setup of steps to recreate the problem

Documentation Changes

  • URL to existing incorrect or incomplete documentation (either in the project’s GitHub repo or external product documentation)
  • Updates required to correct current inconsistency
  • If possible, a link to a project fork, sample, or workflow to expose the gap in documentation.

Feature Requests

  • Complete description of project feature request, including but not limited to, components of the existing project that are impacted, as well as additional components that may need to be created.
  • A minimal, but complete, setup of steps to recreate environment necessary to identify the new feature’s current gap.

The more explicit and thorough you are in opening GitHub Issues, the more efficient your interaction with the maintainers will be.
When creating the GitHub Issue for your bug report, documentation change, or feature request, be sure to add as many relevant labels as necessary (that are defined for that specific project).
These will vary by project, but will be helpful to the maintainers in quickly triaging your new GitHub issues.

Content contributions

We really value contributions. To maximize the impact of your content contributions, we request you follow the procedure and guidelines below. If you are new to open source contribution and would like some more pointers or guidance, you may want to check out Your First PR and First Timers Only.
These are a few projects that help on-board new contributors to the overall open source process.

Forks and Pull Requests best practices

Please ensure you follow these best practices after you read the instructions for contributing. Details are explained in the detailed contribution process description below.

  • One change / documentation update per pull request

    • Always pull the latest changes from upstream and rebase before creating any pull request.
    • New pull requests should be created against a branch of your forked repository.
  • All new contributions should first be tested locally before PR submission.

    • There is a way to run a development instance of the Cloud Pak Playbook site on your local machine. Follow the instructions in the Testing locally section below to set that up. It is very easy.
    • Make sure you test all your changes locally before submitting a pull request.

    The Contribution process step by step - Github and git flow

    The internet is littered with guides and information on how to use and understand git. However, here’s a compact guide that follows the suggested workflow. If you are new to github, or just rusty with the details, it is worth some minutes of your time to study this diagram, relating each step number to its description in the text below. This will help you to understand all the steps in the process, and understand where you are in it as you create your contribution.

    Github flow
    1. Create your own fork of the repo in github. This can be done in the GUI at https://github.com/ibm-cloud-architecture/cloudpak8s by clicking the Fork icon in the upper right corner. A fork or copy of the repo will be created under your own github id. The URL will be:

      https://github.com/<Your github ID>/cloudpak8s
    2. Go to the URL of your forked repo, and use the Clone or download button to copy the repo information so you can paste it into your clone command in the command line to clone it to your local computer.

    3. Add a connection from the master branch of your local cloned repository to the master branch of the upstream repository. The details for this step are in Step 3 Configure Git to sync your fork … of the link below. Do not miss this important step.

      Note: More detail for steps 1-3 here: forking a repo

    4. In a terminal window command line, working from the directory of your local cloned repository, create a new development branch off the targeted upstream branch, which is master.

      git checkout -b <my-feature-branch> master
    5. Do your work:

      • Write your contributions or make your changes
      • Pass your tests locally (see the description of setting up your local test instance below)
      • Commit your intermediate changes as you go and as appropriate
      • Repeat until satisfied
      • See the Testing locally section below for more information regarding running Gatsby locally
    6. When you are finished with all your commits and ready to push your changes, fetch the latest upstream changes (in case other changes had been delivered upstream by others while you were working on your contribution).

      git fetch upstream
    7. Rebase your local cloned repo to the latest upstream changes, resolving any conflicts. This will ‘replay’ your local commits, one by one, after the changes delivered upstream while you were locally developing, letting you manually resolve any conflicts.

      git branch --set-upstream-to=upstream/master
      git rebase

      Instructions on how to manually resolve a conflict and commit the new change or skip your local replayed commit will be presented on screen by the git CLI.

    8. Push the changes you added and commited to your forked repository (see the diagram above to understand this step).

      git push origin <my-feature-branch>
    9. Create a pull request against the same targeted upstream branch. The easiest way to do this is through the GUI. If you go to the upstream repo URL https://github.com/ibm-cloud-architecture/cloudpak8s, after you have done the push above, you should see a notice of your pushed changes and a button to create a pull request.

      Click that button, fill in a general description of the changes in your pull request, and preferably choose one or more reviewers from the list on the right side. Your pull request needs at least one reviewer’s approval before it can be merged. More details on pull requests are in the link below.

      Once the pull request has been reviewed, accepted and merged into the main github repository, you should synchronise your remote and local forked github repository master branch with the upstream master branch. To do so, follow the steps below.

    10. In your local cloned repo command line, change your active branch to master. Then pull to your local cloned repo the latest changes from the upstream master branch (that is, the pull request).

      git checkout master
      git pull upstream master
    11. Now push those latest upstream changes that you just pulled locally to your forked repository.

      git push origin master

      Now your forked repository and your local cloned repository are all caught up and synced with the main upstream repository.

      What Happens to your Pull Request?

      This section is just for your information. You do not have to take any further steps unless you are requested to by the reviewer(s).

      All pull requests are automatically built and unit tested by a Travis-CI pipeline. The pipeline will highlight to the reviewer if there are any missing or mis-matched elements of your proposed change that could create problems for the web site. If any such problems are indicated, the reviewer or maintainer will contact you to request the necessary changes to resolve the issue.

      The repository maintainer will inspect the content your commit. if approved, they will merge your changes into the upstream master branch.

      Should a maintainer or reviewer ask for changes to be made to the pull request, these can be made locally and pushed to your forked repository and branch. This uses the same git add, commit, and push steps on the same development branch that you used when you first created the contribution.

      After the maintainer approves and merges your pull request, your changes will appear on the web site shortly thereafter.

      Testing locally

      Once you have forked the repository and have cloned it to your local system, you can begin contributing. The best way to contribute is to run the Gatsby project (the web site) locally in dev mode. This way, as you are making changes in your development branch, and saving the files in your cloned repo, you can make sure your changes render correctly before creating a pull request.

      1. Once you have cloned your fork of the repository to your local system, navigate to the directory where your project resides.

        cd <your repo directory>
      2. Run the following command to initialize npm in your local directory. This command installs all the dependencies listed in the package.json file.

        npm install
      3. Start Gatsby with the Carbon theme on your local system.

        npm run dev
      4. Open your browser to localhost:8000 to see the pages you are working on and verify that your changes are rendered correctly.

      5. If further changes are required, make your modifications. Gatsby will render the changes immediately.

        For non-Mac users running Linux in a VM:

        1. Gatsby requires Node.js version 10 or above. Run the following command to check your version.
          node -v
        2. Modify the package.json file to update the server with your specific IP address and port number inside “scripts-dev”.
          "dev": "gatsby develop -H <your local IP address> -p 8000"
        3. For additional information, check out Gatsby CLI.