Open Source Development Onboarding Project

Welcome to the Open Source Development team! This is our onboarding project, which is designed to demonstrate how you can learn more about and contribute to a typical open source project.

F in chat for the old onboarding project

This Project is an advanced mathematical calculator that performs a thorough analysis of a select number n. From determining evenness to finding the nth taxicab number, this program will uncover all you ever wanted to know and more.

Getting started

Install Git

You need to have Git installed and set up on your computer.

Windows

We recommend setting up WSL now, as it's very likely that you'll need a Linux environment at some point.

macOS

The "Xcode Command Line Tools" comes with Git. To install it:

• Open Terminal
• Type in git version
• If you see something like this, you're good to go:

  $ git version
  git version 2.32.1 (Apple Git-133)

• If not, you should be prompted to install the "Xcode Command Line Tools"
• After the install finishes, run git version again.

Linux

Use your system's package manager (apt, dnf, pacman, etc) to install Git. The package is usually named git.

Set up GitHub CLI (gh)

The GitHub CLI makes it easy to interact with GitHub using the git command line interface. It logs you in to GitHub.com via your web browser, which means you don't need to manually set up SSH keys or generate Personal Access Tokens (PAT)!

Install on Windows or Linux

Refer to GitHub's documentation on installing gh: https://github.com/cli/cli/blob/trunk/docs/install_linux.md

On Windows, you should use WSL and follow the instruction in your WSL terminal.

If you're on Ubuntu (including WSL), you may run:

type -p curl >/dev/null || (sudo apt update && sudo apt install curl -y)
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
&& sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
&& sudo apt update \
&& sudo apt install gh -y

The commands above do the following:

• Install curl (a command-line HTTP client) if needed
• Configure the apt repo, and download its signing key, for gh
• Install gh

Install on MacOS

On MacOS, you should install gh using Homebrew:

brew install gh

If you don't have Homebrew installed ("command not found" when you run brew), you should install Homebrew. Refer to https://brew.sh for instructions.

Log in to GitHub

Once you have gh installed, run:

$ gh auth login

You should see a prompt like this, and you should select options as shown here:

$ gh auth login
? What account do you want to log into? GitHub.com
? You're already logged into github.com. Do you want to re-authenticate? Yes
? What is your preferred protocol for Git operations? HTTPS
? Authenticate Git with your GitHub credentials? Yes
? How would you like to authenticate GitHub CLI? Login with a web browser

! First copy your one-time code: XXXX-XXXX
Press Enter to open github.com in your browser...
✓ Authentication complete.
- gh config set -h github.com git_protocol https
✓ Configured git protocol
✓ Logged in as XXXX

When it asks you to

Press Enter to open github.com in your browser...

Press Enter, and your browser should open. Paste the 8-character code shown in the prompt, sign in to your GitHub account, and click "Authorize."

Working on the onboarding project

There are many things you can do with the onboarding project. At minimum, you should:

• Locate and take a look at existing Issues and Pull Requests (PR).
• Fork the repo, and clone your fork to your computer.
• Look at the source code, compile, and run it. Use the provided Makefile.
• Make a minor change to any existing file, then commit and push your changes using the git command line.
  • A "minor change" could be anything! For example, you may add a few words to the README, or add a print() statement to welcome.py.
  • Do not edit files with the GitHub web interface!
• Submit a PR with your changes.
  • Provide a descriptive title and description.
  • A good title/description should clearly state what you changed.

You may also:

• Fix an existing issue, improve existing code, or add a new feature. Then, submit a PR with your changes.
• Find an issue in the existing codebase, and report it by creating a new Issue.
• Take a look at other people's PRs, and review their code.
  • If you'd like to do this, ask a lead to add you as a reviewer to a PR.
  • You can approve, request changes, or add comments to the PR.
  • You may also provide specific feedback for specific line(s). To do this, drag and select the line number(s).
• Rebase existing PRs against the main branch, and resolve any merge conflicts.
  • Try to do this with the git command line. Do not use the GitHub web interface.

Tips

Makefile

The provided Makefile specifies these commands:

• make or make release: compile ./welcome, with -O2 and no debug symbols.
• make debug: compile ./welcome_debug, with debug symbols.
• make clean: clean up all compiled binaries.

Some useful Git commands

The following Git commands may be useful:

• git clone
• git commit
• git pull
• git push
• git fetch
• git rebase

If you'd like to learn more about them, consider these resources:

• Learn Git Branching (interactive tutorial)
• Git page on the ArchWiki
• Git's man page: type man git in your terminal, or see here

Recommended reading

• How to contribute to Open Source
• Video that demonstrates basic concepts of Git
• Picturing Git: Conceptions and Misconceptions

License

MIT License