🌟 COSMOS LINK-ER: Your Friendly First Mission

Welcome! You're about to learn something new, and that's exciting. This guide will walk you through everything step-by-step. Take your time—there's no rush.

🎯 What You're Going to Do

You're going to:

  1. Create a GitHub account (if you don't have one)
  2. Get access to our team's code repository
  3. Open a special program on your computer called a "terminal"
  4. Download our team's code library to a folder called COSMOS
  5. Make the LINK-ER scripts executable
  6. Make a tiny, safe change (you can't break anything!)
  7. Save your change properly
  8. Share it with the team

Time needed: About 30-40 minutes at a comfortable pace

🔑 Step 0: Create Your GitHub Account

Before anything else, you need a GitHub account to access our code.

If you already have a GitHub account:

Skip to Step 1! 🎉

If you need to create an account:

  1. Open your web browser and go to: https://github.com/signup
  2. Enter your email address (use a personal or work email you check regularly)
  3. Create a password (make it strong!)
  4. Choose a username (this will be visible to the team—pick something professional)
  5. Verify you're human (solve the puzzle)
  6. Check your email for a verification code
  7. Enter the code on GitHub
  8. Complete any additional setup questions (you can skip optional ones)

✅ You now have a GitHub account!

🚨 Important: Request Repository Access

Once your account is created, you need to be added to the team repository:

  1. Send a message to Zee and Ore with:
    • Your GitHub username
    • A request for access to the vepsservice07-stack repository
  2. Wait for confirmation that you've been added (usually within 24 hours)
  3. Check your email for an invitation from GitHub
  4. Accept the invitation by clicking the link in the email
💡 Tip: Don't continue with the rest of this guide until you've been granted access!

📦 Step 1: Open Your Terminal (and Choose a Better One!)

The terminal is like a text-based way to talk to your computer. Don't worry—it looks intimidating but it's actually just typing commands.

Finding Your Terminal:

On Mac:

The default terminal works, but we recommend iTerm2 for a better experience—it highlights executables and makes everything more colorful!

Using the default Terminal (already installed):

  1. Press Command + Space (this opens Spotlight search)
  2. Type: terminal
  3. Press Enter
  4. A window with black or white background will open—that's it! ✅

Or upgrade to iTerm2 (recommended):

  1. Go to: https://iterm2.com/downloads.html
  2. Download and install iTerm2
  3. Open it from your Applications folder
  4. Much prettier and easier to read! 🎨

On Windows:

Windows Command Prompt and PowerShell don't work well with our tools. You need Git Bash.

Installing Git Bash:

  1. Go to: https://git-scm.com/downloads
  2. Download "Git for Windows"
  3. Run the installer (just click "Next" through all the options—defaults are fine)
  4. Once installed, click the Start button (bottom-left corner)
  5. Type: git bash
  6. Click on "Git Bash" when it appears
  7. A window will open—you're ready! ✅
Why Git Bash? It gives Windows users a Unix-like terminal that highlights executable scripts (files ending in .sh) in green, making them easy to spot!

What you'll see:

A window with text that ends with a $ or > symbol. This is where you'll type commands.

💡 Tip: Keep this window open for the entire guide. Don't close it!

🔐 Step 2: Connect to GitHub

GitHub is where our code lives online. You need to prove it's really you before you can access it.

Copy and paste this command:

gh auth login

How to paste in terminal:

Then press Enter

You'll be asked some questions:

Question 1: "What account do you want to log into?"

Question 2: "What is your preferred protocol?"

Question 3: "Authenticate Git with your GitHub credentials?"

Question 4: "How would you like to authenticate?"

What happens next:

  1. Your browser will open
  2. You'll see a code on the terminal screen—it looks like: ABCD-1234
  3. Copy that code
  4. Paste it into the browser window that opened
  5. Click "Continue"
  6. Log in with your GitHub username and password
  7. Click "Authorize GitHub"

Success! Your terminal should now say: "✓ Logged in as [your username]"

🎉 You did it! You're now connected to GitHub.

📥 Step 3: Download the Code Library (Creating COSMOS)

Now we're going to download all our team's code to your computer into a folder called COSMOS. This is called "cloning."

Type this command exactly:

cd ~/Code

Press Enter

What this does: This moves you to your Code folder—a dedicated place for all your development work. If this folder doesn't exist yet, create it first:

mkdir -p ~/Code
cd ~/Code

Now download the code:

git clone https://github.com/beyvanist/vepsservice07-stack.git cosmos

Press Enter

What you'll see:

This is normal! It's downloading everything. It might take 30-60 seconds.

When it's done: You'll see your cursor blinking again (ready for the next command).

Move into the COSMOS folder:

cd cosmos

Press Enter

What this does: You're now "inside" the COSMOS working directory on your computer. All your work will happen here!

Let's confirm you're in the right place:

ls

Press Enter

What you'll see: A list of files including several .sh files (these are your LINK-ER scripts!)

✅ Perfect! You're in COSMOS—your working directory.

⚡ Step 4: Make All Scripts Executable

The LINK-ER scripts are special programs that help you save your work properly. Right now they're "asleep"—we need to wake them up by making them executable.

🚨 Important: You need to do this for EVERY .sh file in COSMOS

Here's how to make each script executable:

chmod +x commit.sh
chmod +x audit.sh
chmod +x version.sh

Press Enter after each command.

What this does: This tells your computer these scripts are safe to run.

You won't see anything happen after each command—and that's good! No news is good news.

Let's verify they're executable:

ls -la *.sh

Press Enter

What you'll see: A list of .sh files with lots of letters and x's (the x means "executable").

If you're using Git Bash or iTerm2, executable files will appear in green or with an asterisk (*)—much easier to spot!

✅ Great work! The scripts are ready.

💡 Optional: Automate This Step

If you're comfortable with scripting, you could create a simple script that makes all .sh files executable at once:

#!/bin/bash
chmod +x *.sh

Save this as setup.sh, run chmod +x setup.sh once, then just run ./setup.sh in the future. But this is totally optional—running the individual commands works perfectly fine!

👀 Step 5: Look Around (Optional but Cool!)

Let's use one of the tools to see what's here.

./audit.sh

Press Enter

What you'll see:

What this means: You're seeing the current state of everything. Pretty neat, right?

✍️ Step 6: Make Your First Change

Now for the fun part! You're going to add your name to a special file.

Important: Make sure you're in the COSMOS directory. If you're not sure, type:

cd ~/Code/cosmos

Add your name to the registry:

Important: Replace YOUR NAME with your actual name!

echo "YOUR NAME - First LINK-ER Mission - $(date '+%Y-%m-%d %H:%M:%S')" >> OPERATIVES.md

Example:

echo "Sarah Johnson - First LINK-ER Mission - $(date '+%Y-%m-%d %H:%M:%S')" >> OPERATIVES.md

Press Enter

Let's see if it worked:

cat OPERATIVES.md

Press Enter

What you'll see: Your name, the date, and time!

🎊 Amazing! You just modified a real file in the codebase.

💾 Step 7: Save Your Change Properly

This is where LINK-ER's magic happens. Instead of doing complicated git commands, we'll use a friendly helper.

Run the save tool:

./commit.sh --no-verify

Press Enter

What you'll see: A menu with numbered options.

Answer the questions:

Question 1: "Selection:"

Question 2: "Message:"

Question 3: "Scope:"

Question 4: "Finalize?"

Success! You'll see: "✅ Commit successful!"

What just happened?

The tool:

  1. ✅ Packaged your change
  2. ✅ Formatted it in the team's standard way
  3. ✅ Saved it to your computer's copy of the code

Pretty cool, right?

🚀 Step 8: Share With the Team

The last step is sending your change to GitHub so everyone can see it.

First, let's make sure we're tracking the right branch:

Our main branch is called master (not main). Let's verify this is set up correctly:

git branch --show-current

If it says master, you're good! If it says anything else, run:

git checkout master

Now, set up the remote tracking:

This ensures your local master branch knows to push to the remote master branch:

git branch --set-upstream-to=origin/master master

You might see: "branch 'master' set up to track 'origin/master'." Perfect!

Upload your change:

git push

Press Enter

What you'll see:

This means it worked! 🎉

See your change on GitHub:

  1. Open your web browser
  2. Go to: https://github.com/beyvanist/vepsservice07-stack
  3. Click on "Commits" (near the top)
  4. You should see your commit at the very top!

Look at that—your name is in the team's code history!

🏆 You Did It!

Seriously, well done! You just:

That's genuinely impressive for your first time!

🔄 Daily Workflow (For Next Time)

Once you're comfortable, here's what you'll do regularly:

1. Navigate to COSMOS:

cd ~/Code/cosmos

2. Make changes to files:

(Using your normal code editor)

3. Save them properly:

./commit.sh

Answer the questions, then:

4. Share with the team:

git push

That's it! Four simple steps.

❓ Common Questions

"What if I make a mistake?"
Don't worry! Everything you do is tracked and can be undone. You can't permanently break anything.

"What if I see an error message?"
Read it carefully—it usually tells you what's wrong. Most errors are simple fixes like:

"Can I practice again?"
Absolutely! You can add more lines to OPERATIVES.md anytime. Just repeat steps 6-8.

"What do all these commands mean?"

"Why do I need to run chmod +x for every script?"
When you download files from GitHub, they don't automatically have "permission" to run on your computer. The chmod +x command gives them that permission. You only need to do this once per script (unless you re-download everything).

"Who can I ask for help?"
Your team lead is here to help! You can also reach out to Zee and Ore. Don't hesitate to ask questions—everyone was new once.

💭 Remember

Take your time: There's no rush. Go at your own pace.

You can't break anything: Seriously. The worst that happens is you get an error message and try again.

Every expert started here: Even the best developers were once typing their first terminal command.

You're doing great: If you made it this far, you're already learning!

📝 What's Next?

When you're ready to make real code changes:

  1. Edit files in your favorite code editor
  2. Come back to the terminal and navigate to COSMOS: cd ~/Code/cosmos
  3. Run ./commit.sh (without --no-verify this time)
  4. It will check your code for errors before saving
  5. Run git push to share

You've got this! 🌟

Need help? Ask in the team chat or reach out to your team lead, Zee, or Ore. We're all here to support you.

Welcome to the team! 🎉

COSMOS LINK-ER Quick Start Guide v0.2.0