What The Hack - Contribution Guide

What The Hack is all about being “for the people, by the people”. This repo was originally created to share real-world hackathons that Microsoft employees have hosted with their customers. It has since grown to be a learning tool for anyone, anywhere, and follows these core principles:

This document provides the general guidelines for how to contribute to the What The Hack project.

How Can I Contribute?

The best way to contribute is to engage the What The Hack team by submitting an issue via GitHub.

There are multiple ways to contribute:

Before You Start

Before you start contributing and file an issue, make sure you’ve checked for existing issues:

Report a Bug in an Existing Hack

You have found a bug in a hack and want to report it. Great! Something is not right, and it needs to be fixed.

Please go to the Issues page for the WTH repo and create an “Issue/Bug”.

Let us know which hack has the bug. Is it in the Student guide? Coach guide? Is it a documentation issue? Or an issue with a provided resource file or solution file? The form will guide you on what information you should submit. The WTH team will follow up on your submission.

We welcome bug fixes! If you wish fix the bug yourself, please see the section on how to Contribute an update to an existing hack

Propose New Hack Topic or Improvement to Existing Hack

You have a proposal on how to improve an existing hack, or you want to suggest a new hack topic. For improving an existing hack, your proposal should go beyond a “bug fix” and be a fair sized improvement or addition of content.

For new hack proposals, consider:

At this point, you are just giving feedback. You may, or may not, be interested in authoring or updating content yourself. Thanks in advance for your feedback, we can’t wait to read it!

Please go to the Issues page for the WTH repo and create an “Issue/Proposal”.

The form will guide you on what information you should submit. The WTH team will follow up on your proposal.

We welcome new hacks and improvements to existing hacks. If you intend to ‘do the work’ you are proposing, read on for how to:

Contribute a New Hack to What The Hack

You want to author a new hack yourself, or with a team of others, and contribute it to What The Hack.

Please check if there is an existing “Proposal” Issue on the WTH repo to track your new hack. Add a comment to the existing issue to let the WTH team know you are working on this contribution.

If there is no existing Issue for the new hack you plan to contribute, please start by going to the Issues page for the WTH repo and create an “Issue/Proposal”.

In general, the WTH team prefers to collaborate with and assist contributors as they author new hacks. This makes the review process smoother when a new hack is ready to be published via a Pull Request.

By collaborating with the WTH team from the start, it sets your hack up for success by reducing:

We offer the option of collaborating via Microsoft Teams in a “What The Hack” team that we maintain at Microsoft.

You may still choose to develop a new hack independently and submit it for review via the PR process below.

Once you have submitted an Issue/Proposal via GitHub, you can expect the following:

  1. The WTH team will get in touch to start the on-boarding process. If they are aware of other authors with similar proposals, they will schedule a meeting with everyone to see if it makes sense to combine efforts.
  2. The WTH team will add you and any co-authors to the “What The Hack” team in Microsoft Teams and:
    • Create a new channel for you with the name of your proposed hack.
      • You can use this channel to communicate with the WTH team and collaborate with any co-authors.
    • Add a copy of the “WTH Outline Template” to the Files tab of your new channel.
      • You can use this Word template to brainstorm and draft an outline of your hack.
  3. The WTH team will schedule a kick off call with you and any co-authors to:
    • Review the WTH contribution process and set expectations for collaboration between the WTH team and the author(s).
    • Walk through the WTH Author’s Guide.
      • All authors need to read and internalize this document to save you trouble and heartache down the line.
    • Set up a bi-weekly cadence meeting to check-in and address any questions or requests you have during development.
  4. During the cadence meetings, the authors will dictate the pace of the call and report what they have worked on. It is essentially your time to discuss things with the WTH team and/or collaborate with your co-authors. If there is a stint that nothing was worked on, that’s totally fine. We understand and appreciate that most folks are contributing to What The Hack in their spare time.

NOTE: If you are not familiar with Git, GitHub, or Markdown files, you are not alone! Since What The Hack is a collection of mostly course content and documentation, many of our contributors are not developers. It’s out of scope to explain these tools here. However, there are plenty of great resources on the Internet that can help get you up to speed. Here are two to consider as starters:

Also, don’t be shy to ask the WTH team for help navigating Git and GitHub.

Development Process

All contributions to the What The Hack repo come through pull requests. This means that development of a hack starts by forking the What The Hack repo into your own GitHub account. This is where you will do your work. Eventually, you will create a pull request to submit your work back to the What The Hack repo for review.

NOTE: If you are working with a team of co-authors, the team should pick one person to create a fork into their GitHub account. The other authors should collaborate and contribute to that person’s fork during the development process.

Okay, ready to get started creating your own What The Hack?

We have a GitHub Action that automates the creation of a new hack and “scaffolds” out all of the Markdown templates from the WTH Author’s Guide for you. After that, you can open your favorite text editor and start plugging in your content.

The instructions below assume you have the Git command line tool and Visual Studio Code installed on your machine.

  1. Create a fork of the WTH repo
    • Navigate to the WTH repo at: https://aka.ms/wthrepo
    • Click the “Fork” button at the top right of the page and then choose the account you want to create the fork in.
  2. Navigate to your fork of the WTH repo in the browser at: https://github.com/<myGithubName>/WhatTheHack
  3. Click on the “Actions” tab at the top of the page and then select “Create new hack” from the list of “All Workflows” that appears on the left side of the screen.
  4. Click on the “Run workflow” dropdown that appears on the right side of the page and fill in the form that appears with:
    • The name of your hack. Do not use spaces in your hack’s name.
    • The number of challenges you would like your hack to have. We recommend selecting a higher number of challenges than you actually plan to have as it is easier to remove extra challenge templates then add new ones manually later.

    NOTE: Do NOT change the value of the “Run workflow from” field from the pre-selected “branch: master”

  5. Click the green “Run Workflow” button on the form to kick off the GitHub Action. This process will take a couple of minutes to complete. The action will:
    • Create a new branch in your fork with the name of your hack prefixed with “xxx-“. For example: xxx-MyAwesomeHack
    • Create a new folder in the new branch with the same name as the branch: xxx-MyAwesomeHack
    • Create templated markdown files in the new folder for your hack as per the WTH Author’s Guide.
  6. When the GitHub Action has completed running, clone your new fork to your local machine.
    • Open a command prompt with access to the Git CLI and navigate to a folder location on your local workstation where you would like to clone it to.
    • WARNING: Never clone a Git repo to a folder location that is synchronized by cloud service such as OneDrive, Google Drive, etc.
    • Run the git clone command as shown below, then navigate to the WhatTheHack folder that is created afterward. 
      git clone https://github.com/<myGitHubName>/WhatTheHack.git
cd WhatTheHack
  7. Switch to the new branch created by the ‘Create new hack’ GitHub Action. 
    git checkout xxx-MyAwesomeHack

    NOTE: It is a best practice to never work directly on the main/master branch.

  8. Navigate to the new WhatTheHack folder on your local machine and open it with Visual Studio Code or your favorite text editor. In the xxx-MyAwesomeHack folder, you should see Markdown templates as per the What The Hack Author’s Guide:
    • ../
      • Hack Description
    • ../Coach
      • The Coach’s Guide, Lecture presentations, and any supporting files.
      • /Solutions
        • Solution code for the coach only. These are the answers and should not be shared with students.
    • ../Student
      • The Student guide’s Challenge markdown files
      • /Resources
        • The code and supporting files the students will need throughout the hack.
  9. Re-read the What The Hack Author’s Guide (seriously) and make sure your hack follows the templates & styles for consistency. The templates contain in-line instructions and sample text to help guide you.

NOTE: If you have any questions regarding how to use Git/GitHub (commits/push/pull/etc), the WTH V-Team will be happy to help you.

Release Process

When you feel your hack is finished and ready for release, this is the process we will follow:

  1. The WTH team will assign your new hack a number.
  2. You should immediately rename your root folder to use that number. (i.e. “XXX-MyAwesomeHack” to “067-MyAwesomeHack”)
  3. The WTH team will schedule a 60-minute “pre-PR review” meeting with you and any co-authors.
    • The purpose of this meeting is to go through the content together and reduce the amount of back and forth review cycles on GitHub once your Pull Request is submitted.
    • During this review, the WTH team will go through the text with a fine-toothed comb checking for:
      • Adherence to the WTH Author’s Guide
      • All links work, especially the navigation links
      • There are no links to the WTH repo or Coach’s guide from the Student guide (See the WTH Author’s Guide)
      • All images show properly.
      • Any syntax, grammar or punctuation problems that the reviewers see and want you to address. See the Spell Check section for more details.
      • This is NOT a technical content review. As the author(s), YOU are the subject matter experts. The WTH team will trust that you have taken care of the technical bits.
    • NOTE: It is important that you take notes through-out the meeting so that you can go away, make any changes requested, and not miss anything.
  4. Once you have completed any requested changes from the “pre-PR review”:
    1. Fetch the latest updates from the upstream repository (to merge any changes others have made to WTH while you were working on your hack) and ensure there are no conflicts with your hack’s content.
    2. Create a pull request from your fork to submit your work back to the What The Hack repo for review.
  5. The WTH team will review your PR and leave comments if there are any requested changes that still remain. If there are requested changes, please add further comments if you have clarifying questions to ask, or arguments against, the requested changes (that’s ok).
    • NOTE: Make any requested changes by continuing to commit to your fork. The PR will automatically update with your changes. You do NOT need to create a new pull request!
  6. Once you have addressed any requested changes from the WTH team, the WTH team will accept and merge the PR.

Spell Check

A spell checker will run on each new pull request submitted and again each time additional commits are made against that pull request. It will use common English words as well as technical terms from the .github/workflows/spell-check/.wordlist.txt file. The spell checker ignores content within code blocks.

This will run on each pull request that is submitted to the master branch.

If the spell check fails, click the Details link as highlighted in the image below, to reveal the spelling errors that were detected.

Spell Check Fail

The spelling errors will be listed along side of each page that they occurred on as in the image below:

Spell Check Misspelled Words

If the spell checker detects spelling errors, you have 3 options for resolving them:

Use Draft Pull Requests for Early Feedback

If you choose not to collaborate with the WTH team via Microsoft Teams, alternatively you can use a draft pull request.

A good way to communicate before investing too much time is to create a “draft” pull request and share it with the WTH team. You can do this by selecting “Create Draft Pull Request” when opening a pull request. This will let people looking at your PR know that it is not well baked yet.

The WTH team will review your new hack following the same guidelines as above. However, the process will take longer if we need to spend additional cycles going back and forth within GitHub’s PR process.

Contribute an Update to an Existing Hack

If you are planning to fix a bug or implement an update for an existing hack, please check if there is an existing Issue on the WTH repo to track it. Add a comment to the existing issue to let the WTH team know you are working on this contribution.

If there is no existing Issue for the update you plan to contribute, please start by going to the Issues page for the WTH repo and create one:

To contribute an update to an existing hack, you should:

  1. Fork the What The Hack repo into your own GitHub account.
  2. Create a new branch in your fork. This is where you will do your work. (NOTE: It is a best practice to never work directly on the main/master branch so that it always reflects the state of the upstream main WTH repo.)
  3. When you have completed the update in your fork:
    1. Fetch the latest updates from the upstream repository (to merge any changes others have made to WTH while you were working on your update) and ensure there are no conflicts with your updates.
    2. Create a pull request from your fork to submit your work back to the What The Hack repo for review.

The WTH team will review the Pull Request with an eye towards compliance with the WTH Author’s Guide, as well as any spelling or grammar issues. These reviews are generally shorter if the update is by one of the hack’s original authors.

If the update is from a new contributor, the WTH team will request one of the original author’s of the hack to review the update for technical accuracy.

Ask for Help Hosting a What The Hack

We’ve put together a lot of guidance on how to host a What The Hack event in our WTH Hosting Guide. We also have a 60 minute video available that explains the hosting process here: What The Hack - Technical Train the Trainer Tech Talk.

If you have further questions, or want to get in touch with the What The Hack team to learn more about hosting a WTH event, please go to the Issues page for the WTH repo and create an “Issue/Request”.

NOTE: What The Hack is self-serve content. The WTH team does not offer logistical support or Azure environments. The WTH team will make its best effort to connect you with hack authors for details on the technical content, or answer any other questions you have about hosting an event.

Let Us Know Where You Have Used What The Hack

The BEST feedback you could share is to let us know how and where you have used What The Hack content. Our hacks’ authors are always excited to learn if their content is being used. We would love to know delivery dates, # of attendees, locations (if in-person), and how it impacted your attendees’ technical readiness.

If you have found this content useful, or hosted a WTH event, please go to the Issues page for the WTH repo and create an “Issue/Report”.

NOTE: Reporting that you hosted a What The Hack event this way will be publicly viewable. You should NOT share the name of the organization you hosted an event with unless the organization has given permission to share its name publicly.

Thank You!

Your contributions to open source, large or small, make projects like this possible. Thank you for taking the time to contribute.

And now the fine print…

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution.

For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.

Use of Third-party code

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.