Skip to content

Latest commit

 

History

History
171 lines (130 loc) · 10.9 KB

ContributionGuide.md

File metadata and controls

171 lines (130 loc) · 10.9 KB

How to Contribute to Halloween Jam

Table of Contents

  1. Overview
  2. Making Documentation Changes
  3. Adding Files to GitHub
  4. How to Download and Run Locally
  5. How to Make Local Changes
  6. Submit Changes with Pull Requests

Overview

Below are guides on how make different types of changes. If you are adding files or updating documentation, there is no need to download the whole project. If you are adding content into the actual game, programming, or testing, you'll need to refer to the download instructions.

If you need help with your changes, reach out to the project owner.

Making Documentation Changes

Documentation is one of the key areas that keep projects like HalloweenJam running smoothly. As multiple people are working on the project, being able to find information is crucial to keep game development efficient.

If working with a shareable document, such as Google Docs or Kanban boards in Trello, simply follow the appropriate link and start editing. Certain documents may limit direct edits to subsets of people. If you feel you should have security to make changes and cannot, reach out to the project owner.

If you are making changes to GitHub documentation, such as README.md, follow these steps:

  1. In the upper-left corner of GitHub, there is a dropdown menu with branch names, a button labelled 'branches', and a button labelled 'tags'. In the dropdown menu, make sure 'development' is selected.
  2. Find and click/open to the file in GitHub
  3. In the upper-right corner, click the pencil icon
  4. Make your changes
  5. Click the 'Preview' button to review your changes
  6. Scroll to the bottom of the screen and enter a message briefly describing your changes
    • This is the smaller box, not the 'Add an optional extended description...'
  7. Ensure the 'Commit directly to the development branch' radio button is selected
  8. Click the 'Commit changes' button
  9. Create and submit a Pull Request

Adding Files to GitHub

If adding content, such as artwork or sound files, you may not need to download the whole project. Instead you may add these files directly to GitHub. You can add files by following these steps:

  1. In the upper-left corner of GitHub, there is a dropdown menu with branch names, a button labelled 'branches', and a button labelled 'tags'. In the dropdown menu, make sure 'development' is selected.
  2. Navigate to the folder in GitHub where you want to upload the file
  3. In the upper-right corner, click 'Add file >> Upload files'
  4. Either click 'choose your files' and browse to your desired files or drag and drop the files
  5. At the bottom of the screen, enter a message briefly describing your changes
    • This is the smaller box, not the 'Add an optional extended description...'
  6. Ensure the 'Commit directly to the development branch' radio button is selected
  7. Click the 'Commit changes' button
  8. Create and submit a Pull Request

How to Download and Run Locally

Downloading the Project

Using Git + Command Line

For this method, you will need to have Git installed on your computer. Git is a free source-control software. If not already installed on your computer, it can be downloaded here.

  1. Open either PowerShell or a terminal window
  2. CD to the directory you want to store your copy of this project
  3. Enter git clone https://github.com/zkturman/HalloweenJam.git
    • You may be prompted for credentials at this stage. You can set these properties using a one-time command.
      • git config --global user.name "John Doe"
      • git config --global user.email johndoe@example.com
    • You may also be prompted for GitHub credentials or a personal access token. Following the steps here will help you configure Git to prevent continued harassment.
      • Treat this token like a password and keep it CONFIDENTIAL.
      • Git should remember this token once you successfully complete an action using the token and restart the terminal.
  4. Enter git checkout development

Using SourceTree

For this method, you will need to have SourceTree installed on your computer. SourceTree is a free Git GUI (as in, you don't need the command line). It can be downloaded here. If you haven't already installed Git, you will need to install it as well. Git can be downloaded here.

  1. Open SourceTree
  2. Open a new tab and click the 'Clone' button
  3. In 'Source Path', enter https://github.com/zkturman/HalloweenJam.git
    • Note: this can be copied above by clicking the grey/green Code button and copying the HTTPS URL
  4. In 'Destination Path', enter the location on your computer you want this repository to be copied into
  5. In 'Name', enter the name you want for your local project folder. E.g., HalloweenJam
  6. Click 'Advanced options' and change 'Checkout branch' to 'development'
  7. Click the 'Clone' button

Running the Project

To run this project, you will need UnityHub installed on your computer. It can be downloaded here. Once downloaded, you will need to download Unity version 2021.3.11f1. To install this version, follow these steps:

  1. Open UnityHub
  2. Click the 'Installs' tab (on the left)
  3. Click the 'Install Editor' button
  4. Locate version 2021.3.11.f1 in the 'Official Releases' tab
  5. Click the 'Install' button

To open the HalloweenJam project:

  1. Open UnityHub
  2. Click the 'Projects' tab on the left (if not already selected)
  3. Click 'Open' >> 'Add Project from Disk'
  4. Select your HalloweenJam folder
  5. Click 'Add Project'
  6. If the project does not open automatically, click the HalloweenJam row in UnityHub to open the project.

Currently, there are no special run or build instructions. If you would like to run the game from the start, follow these steps:

  1. Navigate to the Assets\Scenes\ directory within Unity
  2. Double click 'HomeScene'
  3. Click the Play button at the top of the Unity window

How to Make Local Changes

After following the instruction in How to Download and Run, you can make the desired changes on your machine within your copy of the project.

NOTE: YOU SHOULD ALWAYS PERFORM A PULL BEFORE MAKING CHANGES TO AVOID CONFLICTS

  • In Git, git pull
  • In SourceTree, click the 'Pull' button

Once finished with your changes, you will need to perform some actions to get them onto GitHub (called 'pushing'). Once your changes are 'pushed', you can create a Pull Request as described below. We will then review your changes and add them to the main branch of source code.

Using Git + Command Line

  1. Open either PowerShell or a terminal window
  2. CD to your HalloweenJam directory
  3. Enter git status and review all the files you've made changes to.
    • If you have unwanted changes, you can undo all changes to a file using this command: git checkout HEAD -- my-file.extension
  4. To prepare these changes for saving, enter git add ., which will add all your local changes.
    • If you would like to add only some changes, replace . with a filename.
  5. To officially save these changes, enter git commit -m "COMMIT MESSAGE THAT DESCRIBES YOUR CHANGES"
  6. Finally, enter git push to send those changes to GitHub.
    • If Git says your local repository is not up to date with remote, you must enter git pull first. This command will update your local files with all new changes to the repository. If this creates merge conflicts, you will need to fix them and redo these steps. See here for help. There are other strategies for handling this scenario, but approach with caution.
  7. Create and submit a Pull Request

Using SourceTree

  1. Open SourceTree
  2. Open your HalloweenJam tab/repository
  3. Click the 'Commit' button and add a message that describes your changes
  4. Click the 'Stage All' button, or select certain files and click the 'Stage Selected' button
  5. Tick the 'Push changes immediately to ' checkbox
  6. Click the 'Commit' button
    • If your repository is out of date, you may need to click the 'Pull' button first. If this creates merge conflicts, you will need to fix them and redo these steps. See here for help.
  7. Create and submit a Pull Request

Submit Changes with Pull Requests

Creating a Pull Request is how you get your changes incorporated into the main project. All changes are initially added to a development copy (i.e. the 'development' branch) of the project, and a Pull Request is the process needed to add changes from this copy to the main project.

In GitHub, click the 'Pull requests' tab above, or this link. If your changes are recent, you may see a banner stating so, and you can follow these steps:

  1. Click the 'Compare & pull request' button
  2. Scroll down to review the changes are yours
  3. Add a brief comment describing your changes
  4. Click the 'Create pull request' button
  5. On the right, under the Reviewers section, add someone and contact them letting you know you've created a pull request.
  6. Someone will review and (hopefully) add your changes to main

If you do not see a banner concerning your changes, follow these steps:

  1. Click the 'Pull requests' tab at the top of the screen
  2. Click the 'New pull request' button
  3. Click the branch with your changes (usually development)
  4. Review the changes to make sure they're your changes
  5. Click the 'Create pull request' button
  6. Add a brief comment describing your changes
  7. Click the 'Create pull request' button
  8. On the right, under the Reviewers section, add someone and contact them letting you know you've created a pull request.
  9. Someone will review and (hopefully) add your changes to main

Back to Home