Setting Up Your Dev Environment

Unlike some software teams, we do not want you to push your work directly to this repo. Instead, we would like you to fork this repo to your own private GitHub account and make all pushes to that repo, after which you can create pull requests from your forked repo to this one.

If you run into problems at any point during this setup process, you can message our team lead, Matthew Lewis, on Slack for help. (If you are not already on the NGCP slack, see Getting Connected)

Instructions

Software Installations

You will need to install certain pieces of software onto your computer. This section will guide you through that process.

Git

Git (different from GitHub) is a version-control software that GitHub is built around.

1. Check if Git is already installed: run git --version on your command-line
2. If you get an error, follow the steps for your OS to install Git on your computer here: https://www.atlassian.com/git/tutorials/install-git

Python

Python is the primary language our code will be written in, so you will need to install the Python interpreter.

1. Check if Python is already installed: run python3 --version on your command-line
2. If you get an error, follow these steps to download and install Python:
   1. Navigate to this Python webpage: https://www.python.org/downloads/mac-osx/
   2. Click on the link that says "Latest Python 3 Release - Python 3.X.X", where "3.X.X is the latest version, like 3.9.1 for example. It should be at the top of the webpage
   3. Scroll down to the bottom of the webpage, where it says "Files"
   4. Download and run the appropriate installer for your OS

Pip

Pip is a package management system that will install and manage Python packages for you.

1. Check if Pip is already installed: run pip3 --version on your command-line
2. If you get an error, run these commands on your command-line to download and install Pip:
   1. curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
   2. python3 get-pip.py
   3. rm get-pip.py (Mac/Linux) or del get-pip.py (Windows)

QGroundControl

QGroundControl is a drone simulator application we will be using to test our code.

1. Check if QGroundControl is already installed: Go to your computer's Applications folder and search for QGroundControl
2. If you did not find it, follow the instructions to download and install QGroundControl here: https://docs.qgroundcontrol.com/master/en/getting_started/download_and_install.html

Now that you have all the software you need, you can move on to the next section.

Cloning to Your Local Machine

1. Navigate to the NGCP HEX repo: https://github.com/NGCP/HEX
2. Find the green button on the homepage, labeled "Code", and click on it to open a drop-down menu (Note: This is not the grey tab labeled "Code" in the top left corner)
3. If you have SSH set up with git, click the "SSH" tab. If you don't, or don't know what that means, click the "HTTPS" tab
4. Click the clipboard icon to the right of the text string generated by Github. This will copy a reference to this repo to your clipboard
5. Open the command-line interface for your OS (e.g. Terminal for MacOS, Command Prompt for Windows)
6. Navigate to a directory that you would like to contain your local copy
7. Run the following command: git clone repo-reference, where repo-reference is what you copied on GitHub in Step 3. This will create a new folder in your current directory and fill it with everything from the GitHub repo as well as a hidden .git folder that enables Git to track your repo locally
8. Navigate into the newly created HEX directory
9. Run the following command: git remote set-url --push origin no-pushing. This will make it so you don't accidentally push your work straight to the NGCP repo

You now should have a working copy of the NGCP HEX repo on your local machine. Next you will need to create a fork of the GitHub repo that you will push your work to.

Forking This Repo

1. Navigate to the NGCP HEX repo: https://github.com/NGCP/HEX
2. Find the button labeled "Fork" in the upper right hand corner of your screen, and click on it
3. Select which account you want to fork this repo to. GitHub will list any private accounts you have as well as any GitHub organizations you are a part of. Make sure to select the private account you would like to contribute with

You should now be viewing your own copy of this repo, saved to your own account. The only thing left to do is get your development environment configured properly, which the next section will cover.

Configuring Your Dev Environment

Setting Up Push Access to Your Forked Repo

In order to be able to push changes that you make from your local copy to the fork you made, you will need to add that repo as a remote (a Git term that means a remote, or separate, repository that you would like to interact with).

First, go to the homepage of your forked repo, and follow Steps 2-4 of Cloning to Your Local Machine.

Now, on a command line, navigate into the directory containing your local repo, and run this command:
git remote add myfork repo-reference, where repo-reference is what you copied on GitHub

Finally, run a git pull followed by a git push myfork main to make sure everything works and is up to date.

Creating a Python Virtual Environment

It is highly recommended to use a virtual environment for running Python. To create the virtual environment, run python3 -m venv venv in your repo directory. This will create a folder in that directory called venv that contains all of the files needed to run the virtual environment.

Mac/Linux: To activate the environment, run . venv/bin/activate. If this is successful you should now see (venv) as a prefix to your shell prompt. You only need to be in the virtual environment if you are installing Python packages (like with Pip, for example) or running Python code.

When you are done working, run deactivate to deactivate the environment.

Windows: To activate the environment, run . venv/Scripts/activate. If this is successful you should now see (venv) as a prefix to your shell prompt. You only need to be in the virtual environment if you are installing Python packages (like with Pip, for example) or running Python code.

When you are done working, run . venv/Scripts/deactivate to deactivate the environment.

Installing Dependencies

There are a number of Python packages that you will need to be able to run the source code.

To install them, navigate into the project directory, and activate your virtual environment. Next, run pip3 install -r requirements.txt.

You only need to do this once, not every time you use your virtual environment.