Skip to content

Getting Started

Jump to bottom
kaylee-xie edited this page Jun 29, 2025 · 16 revisions

Getting Started:

1. Installing VS Code

It is highly recommended that you use Visual Studio Code (VS Code) for this project. All instructions below will assume that you are using this editor. If you prefer to use a different editor, that is acceptable, but it may be more difficult to get help when getting started.

To install VS Code:

  1. Go to https://code.visualstudio.com/download and download the installer for your operating system.
  2. Run the installer and follow the setup instructions.

VS Code Extensions:

Extensions are small add-ons that enhance VS Code's functionality. Make sure you install the following extensions:

  • Better Comments (by Aaron Bond)
  • Python Extension Pack (by Don Jayamanne)
  • Error Lens (by Alexander)
  • GitLens (by GitKraken)
  • Path Intellisense (by Christian Kohler)
  • Black Formatter (by Microsoft)

2. Installing Python

Ensure that you have Python 3.12 installed on your system by running the following command:

python3 --version

This command will display the version of Python 3 that is installed, such as Python 3.12.10.

If you are using Windows, or if the python3 command does not work (common on Windows), try:

python --version

This command will display the version of Python that the python command points to.

If Python is not installed, or you need a different version, follow the installation instructions for your operating system from the official Python documentation: https://www.python.org/downloads/.
NOTE: We are package locked to python 3.12 so you may encounter issues with newer versions. It does not matter whether you use Python 3.12.9, 3.12.10, or any other 3.12.x version.

3. Project Setup

⚠️ Read through this entire section for project setup before you start applying the instructions in your editor. This is necessary to avoid mistakes!

You'll need to clone the repository containing the project. To set it up:

  1. Open VS Code (or your preferred editor, but all following instructions will be in terms of VS Code)
  2. Go to: File → Open Folder. Choose or create a folder for your repository.
  3. Open a terminal: Terminal → New Terminal
  4. In the terminal, run the following commands:
# Method 1
git init
git remote add origin https://github.com/CApy-RPI/onboarding
git pull origin main

This will initialize a Git repository in your folder, connect it to the onboarding project, and download all materials from onboarding.

Alternatively, you can use the following commands:

# Method 2
git clone https://github.com/CApy-RPI/onboarding
cd onboarding

The git clone command essentially does everything the above 3 commands do, just in one step. The cd command is necessary to change the directory.

⚠️ Important: Do not do both methods. If you use git clone, it already sets up everything. You do not need to run git init, git remote add origin, or git pull. The same applies the other way around.

Why? Running both methods will cause Git errors or duplicate files. Thus, avoid doing so!

In the future, if you need to open a new directory and download materials for a different project, you will use one of the two methods, but replace the link. For example:

# First method
git init
git remote add origin https://github.com/CApy-RPI/other-project
git pull origin main

# Second method
git clone https://github.com/CApy-RPI/other-project
cd other-project

4. Managing Dependencies

4.1 Dependency Management

In CAPY, we will use a Virtual Environment - A tool that helps keep Python packages for each project separate. Using a virtual environment helps prevent conflicts when projects require different versions of the same package.

A virtual environment creates a local folder that has its own copy of the Python interpreter and its own place to install packages. This ensures that packages for one project do not affect others.

If you are on Windows, it is strongly recommended to use Command Prompt (cmd), since it works most reliably with .venv and Python.

Use the following commands to create and activate the virtual environment:

# Create the virtual environment
python -m venv .venv

# Activate it on Windows
.venv\Scripts\activate

# Activate it on Unix/MacOS
source .venv/bin/activate

If you successfully created and activated the virtual environment, you should see (.venv) at the beginning of your terminal prompt (in VS Code). This indicates that your virtual environment is active and ready to use.

🔍 To double check:

  • On Windows: Run where python
  • On Mac/Linux: Run which python

The result should point to .venv\Scripts\python.exe on Windows, or .venv/bin/python on Mac/Linux.

4.2 Installing Requirements

The pip command is the standard package installer for Python. With this, you can download, install, and manage packages from the Python Package Index.

  • With the pip install command, you download the package and any other packages it depends on, and install them into your current environment.

Use requirements.txt for production dependencies and requirements_dev.txt for development dependencies:

# Install production dependencies
pip install -r requirements.txt

# Install development dependencies
pip install -r requirements_dev.txt

4.3 requirements.txt vs requirements_dev.txt

  • requirements.txt: Contains the dependencies required for the application to run in production.
  • requirements_dev.txt: Contains additional dependencies required for development, such as testing and linting tools.

Example requirements.txt:

discord.py      # For building Discord bots & interacting with the Discord API
pymongo         # Stores data that is easy to read & work with in code

Example requirements_dev.txt:

pytest       # For writing & running tests
flake8       # For checking code style & linting
black        # For formatting code
mypy         # Checks if type annotations are correct

4.4 .env

  • Use a .env file to hold all sensitive access tokens.
  • Ask your project lead for access to these tokens.
  • The .env file must be located in the directory from which you run the bot.

⚠️ Important: Do not share any of the contents in your .env file. Doing so could put the security of your project at risk. Always keep this file private and ensure it is not committed to version control (GitHub).

5. Running the Bot

Method 1:

.venv\Scripts\activate
python src/capy_app/main.py

If using the above to run the bot: .env must be in src/

Method 2:

  1. Assuming you are using VS Code, at the top left select Run → Add Configuration... → Python Debugger → Python File.

  2. At this point, you should have a launch.json file open. Change the program: field to "src/capy_app/main.py".

  3. Now, you should be all set to run. In the top left again, go to Run → Start Debugging.

6. Creating your own Bot

It is necessary to create your own bot, separate from the CAPY DEV bot, to use for testing.

The CAPY DEV bot is a shared resource. If too many people run the bot at the same time, it can lead to resource limitations and performance problems.

Thus, by creating your own bot, you can test your code freely and experiment without disrupting others.

Steps to Create Your Own Bot:

  1. Go to https://discord.com/developers/applications.
  2. In the top right, select New Application. Give it a name. Click Create.
  3. On the left, you should see a Bot tab. Under that tab, you can customize your bot:

    • For the USERNAME, name it CAPY-your_name, with your first name.

    • Under Privledged Gateway Intents, check the Presence Intent, Server Members Intent, and Message Content Intent.

    • Under Bot Permissions, check Administrator.

  4. Under the USERNAME field you previously filled out, you should see a Reset Token button. Click it and copy the token provided. Do not share this token or commit it to GitHub.
    • In VS Code, navigate to your .env file. At the top, you should see a BOT_TOKEN=[token] already. Paste your token there. Save the file.
  5. On the left, you should see an OAuth2 tab. Under that tab, navigate to OAuth2 URL Generator.
    • Under SCOPES, select bot.
    • Under BOT PERMISSIONS, select Administrator.
    • Ensure the INTEGRATION TYPE is Guild Install.
    • Copy the generated URL and send it to your team lead. They will add your bot to the CAPY server.

And there you have it! Once your bot is added to the server, you will be able to test your code freely and safely. Happy coding!

7. Linear

Linear is a project management app that we will use to organize tasks, track bugs, and manage progress.

Your team lead will be sending you an invitation to our Linear workspace soon, if they haven't already. Access that link and create an account with your RPI email.

7.1 Basics of Linear

We will be using Linear to manage our work by viewing assigned tasks, creating new issues, updating their status, and collaborating with teammates directly within each issue.

To get started, look at the left-hand sidebar and go to Your teams → CAPY DEV. Click on the Issues tab.

You should see a layout similar to the image below.

Image

This tab is where we manage all the tasks we are working on, need to work on, or have worked on for CAPY. They can be individual or collaborative, this is up to you!

For our project, we follow a flexible and self-driven work style. You are encouraged to work on whatever tasks interest you, as long as you:

  • Stay productive
  • Complete you work on time
  • Contribute meaningfully to the team's progress

This means that you have the freedom to choose issues that interest you, ranging from coding a feature to helping with graphic design. Pich what you are excited about, or think about where you can contribute the most!

That being said, you should keep in mind that you should be working on something relating to CAPY. You are here because you are part of this team and are committed to this project — not just to skim by or do the bare minimum for a grade.

Assigning a Task

Let's say you have found an issue that you would like to work on in the Issues tab. If you want to work on it, you will need to assign it to yourself.

To do this, hover over the issue you would like to work on and look to the far right — you will see an icon that resembles a person. Click on that icon and a dropdown will appear where you can select your name.

Once assigned, your avatar will appear next to the issue, which lets the rest of the team know that you are working on it.

If you would like to learn more about the functions of Linear, please navigate to the following link: https://linear.app/docs.

For information about creating a branch with Linear, navigate to the Quality-Driven Development & Contribution branch of this Wiki.

Clone this wiki locally