Skip to content

How to contribute to the Playbook#

Overview#

The Playbook is developed in Markdown format (.md) and stored in a GitHub repository for updates and collaboration. To contribute, you need to be familiar with Git.

The preferred tool is VSCode with the following extensions:

  • Markdown All in One
  • markdownlint

Learning Objectives

You will learn

  • how to install VSCode and Git.
  • How to use Git with VSCode
  • How to write for the Playbook

Step by Step Process#

Installing VSCode and Git#

To install VSCode, follow instructions below:

  1. To install Github in your laptop follow this Git Installation guide

  2. Once you have installed Git, you need to order a Github account for yourself and familiarize yourself with Git. You can start with the below resources

Stop

Before proceeding, ensure you have a valid NN Github account ordered and delivered. You can test this by going to https://github.com/innersource-nn. It should direct you to SSO sign in page and should not ask you for any other credentials.

You can now continue to the rest of the guide.

By now, you should have some basic understanding of Git and are ready to contribute. Follow along below

Working with Git to contribute to the Playbooks#

Playbooks are developed and maintained in dataplaybook Github repository. Clicking on the link will open the repo in the browser.

You have two options

  1. You can work with Git in VSCode via the source control user interface. There's a guide on how to do this in intro-to-git page
  2. You can also work via command line interface in the terminal of VSCode. This gives you more control. You can follow the below guide for using Git CLI.

Success

  1. Even though command line gives better control, it might not be intuitive for non-technical users. The best way to overcome this is by using a combination of VSCode to do commit and sync to local branch while using git push to push to remote.

  2. Smaller commits are easier to manage and push

  3. Commands like 'git status' and then merging main with your own branch always ensures you have the most updated branch. Here is a cheat sheet that will help you along the way.

Command Line Approach for finer control#

  1. Clone the repository

    git clone https://github.com/innersource-nn/dataplaybook

    Read more about what is "Clone the repository?"

  2. Create your own branch

    Read more about What is a branch and how to create it.

    Name your branch informatively, using the path to the file or folder (if you intend to modify multiple files) and your name.

    Example

    example-doc/playbooks/data_product_creation/ideation.

    This naming convention helps ensure clarity when navigating multiple branches, making it easier to select the correct one for demo-ing and merging.

    Don't forget to checkout to the new branch

    Workflow example

        git branch example-doc/playbooks/data_product_creation/ideation  
    git checkout example-doc/playbooks/data_product_creation/ideation

  3. Make your changes to the code, push when ready, create a PR

    Read here Changes, Commits and Pushes to remote

    Workflow example after changes are made

        git add *  
    git commit -m "added outputs section"
    git push

How to Write a page in the playbook#

  1. Refer this section to understand how a page should look like
  2. Refer this section to understand page formatting

Next Steps#

Create a Pull Request (PR) to have your changes merged to the main branch.
Request the Playbook repo owners to review your PR.