Skip to content

Latest commit

 

History

History
190 lines (132 loc) · 6.7 KB

CONTRIBUTING.md

File metadata and controls

190 lines (132 loc) · 6.7 KB
Raw

Contributing to the Online Product Engineering Dojo training

We ❤️ Pull Requests for fixing or adding content. Thanks in advance for any contribution you may make.

For small changes, you can simply use the "Edit" button to update the Markdown file or any of the dialogs, and start the pull request process easily. You can use the preview tab in GitHub to make sure the updated content is properly formatted before committing. Once the pull request is placed, review the results of the pipeline and correct any mistake that is reported.

If you plan to contribute often or have a larger change or changes to make, it is best to setup your local environment for contribution.

The instructions for doing so are provided in the remainder of this page.

Development Environment Setup

This guide provides steps to setup a dedicated environment for Online Product Engineering Dojo development. It includes Git and Katacoda related instructions.

Prerequisites

Before you get started make sure to perform the one time setup:

Development Process

Steps below illustrate how to work on a new Product Engineering Dojo feature. See the Katacoda and branches section for more details why the development is done directly on fork's main branch.

  1. Fetch latest changes from main repository:

    git fetch upstream

  2. Reset your fork's main branch to match exactly upstream main:

    git checkout main
git reset --hard upstream/main
git push --force

    IMPORTANT: Only perform this step when you start working on new feature as the above commands will overwrite completely your main content.

  3. Hack, hack, hack, and commit your changes to Git:

    # hack, hack, hack
git add ...
git commit ...
git push

  1. Your changes should be visible in Katacoda at h​ttps://katacoda.com/<your_katacoda_user>

  2. To continue development of your feature:

    # hack, hack, hack
git add ...
git commit ...
git push

  3. Open a new Pull Request to the main repository using your main branch

Katacoda and Branches

Katacoda only works with main branch. Therefore you will use your fork's main branch to preview your work in Katacoda. To make the Pull Requests and merges easier, at the beginning of each feature development we will reset your main to match exactly the main of the main repository.

If you have reasons to not reset your fork's main branch, you can use feature branches, and then merge their content to your main and create Pull Requests out of the feature branch:

git fetch upstream
git checkout -b feature-X upstream/main
# hack, hack, hack
git add ...
git commit ...
git checkout main
git merge feature-X
git push
# changes now visible in Katacoda
git checkout feature-X
git push -u origin feature-X
# you can now open a Pull Request to the main repository using feature-X branch
# finally once all done - delete the branch
git branch -d feature-X
git push --delete feature-X

GitHub Repository Clone

Online Product Engineering Dojo development is managed with one repository:

To prepare your dedicated GitHub repository:

  1. Fork in GitHub https://github.com/dxc-technology/online-pe-dojo

  2. Clone your forked repository (e.g., h​ttps://github.com/user123/online-pe-dojo ) to your workstation.

  3. Set your remotes as follows:

    cd online-pe-dojo
git remote add upstream git@github.com:dxc-technology/online-pe-dojo.git
git remote set-url upstream --push DISABLED

    Running git remote -v should give something similar to:

    origin  git@github.com:user123/online-pe-dojo.git (fetch)
origin  git@github.com:user123/online-pe-dojo.git (push)
upstream        git@github.com:dxc-technology/online-pe-dojo.git (fetch)
upstream        DISABLED (push)

    The use of upstream --push DISABLED is just a practice preventing those with write access to the main repository from accidentally pushing changes there.

Katacoda Setup

https://katacoda.com is lab environment used by Online Product Engineering Dojo that allows students to have dedicated environments for their class right in the browser.

  1. Sign up for new account on https://katacoda.com

  2. If that is your first visit, go to Claim Your Profile page and provide your username and name. Make sure to SAVE and then abort GitHub configuration as it does not allow to configure a non-public repository.

  3. Go to Your Profile page and then click on Settings icon in the middle of the page

  4. Set Private Git Repository to Yes

  5. Set Git Scenario Repository to the address of your fork (e.g., h​ttps://github.com/user123/online-pe-dojo )

  6. Make sure to click on SAVE button

  7. Do not close this window as we will need the values from Git Deploy Key and Git Webhook Secret

GitHub Webhook Setup

We now need to configure GitHub repository hook so that Katacoda is notified each time you push updates to your repository.

  1. Open new browser window and go to your fork's URL (e.g., h​ttps://github.com/user123/online-pe-dojo )

  2. Open the repository Settings page tab and then Deploy keys (left navigation)

  3. Click on Add deploy key button and use the following information to set it up:

    • Title: katacoda.com
    • Key: paste the Git Deploy Key value from your Katacoda settings page
    • Allow write access: leave unchecked

  4. Click on Add deploy key button

  5. Click on Webhooks (left navigation)

  6. Click on Add webhook button and use the following information to set it up:

  7. Click on Add webhook button to create it

If the setup is done correctly you should be able to access your Katacoda environment at:

h​ttps://katacoda.com/<your_katacoda_user>