Onboarding
Note for MacOS users: You may want to install Homebrew2 first before you install Git
Download Homebrew
Steps for installing Homebrew by Yash:
- First open Terminal on your laptop
- Copy this into your terminal space:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" - It should ask you to enter your laptop login password
- It will now install homebrew
- Once installed, read Terminal, it should prompt you to type something along the lines of
brew help - Let that run its course, after this, you are now able to install git by entering
brew install git
Astro will be installed in the repository, once you run npm install. To parse the syntax, an extension called 'Astro' can be installed through 'Extensions' on Visual Studio Code to view the syntax.
HIGHLY RECOMMENDED: GitHub Desktop - Allows you to make changes using Git without needing a Command Terminal
Houston watches you code and you get some cool colours too!
The PM and TL will be in charge of creating most of the tickets as time passes, but once we get the base requirements up and going, we are open to hearing any ideas for future tickets. :)
If any of these terms are new to you, please refer to the FAQ at the bottom of this page.
On Jira, a ticket5 will be assigned to you in the To-Do column, in Jira6. This task represents a task for you to complete in the next sprint cycle. For this example, we have the ticket 'Add Houston to the README'.
To work on the ticket, you can create a branch7 in GitHub that is linked to it.
Important: You must include the issue key in the name of the branch* to link it to the Jira ticket.
In this case, it would be ORAKEI-3. One common way to do this is using git checkout on the Command Line, for example, git checkout -b ORAKEI-3-<branch-name> where <branch name> is whatever you want to call the branch.
*Note that the branch name cannot have spaces, instead use dashes ('-') to separate words.
You will now be looking at this branch. Once you make your changes on your branch, you can make commits and add the issue key to the name of your commit. This will allow any commits to be seen within the associated Jira ticket. You can use GitHub Desktop, Visual Studio Code, or the Command Line to make your commits. I will use Visual Studio Code's built-in committing system for our example.
Remember always to PLEASE COMMIT YOUR CHANGES OFTEN to your branch! (We don't wanna lose our progress here. This will also show the project execs that we're being productive ;) )
You can commit using the Command Line with the command git commit -m "commit message".
For example, the commit message could be git commit -m "ORAKEI-3 feat: Added Houston to the README" where feat stands feature, meaning we added a 'feature' to the program.
GitHub Desktop makes it easier, with just the click of a button:
You may move your ticket from the To Do column to the In Progress one during this stage.
Note: If you want to use the command line to publish your branch, you can use this command: git push -u origin <branch>.
If you did this step correctly, you should see a branch icon that you can hover over pop up in the corresponding Jira ticket.
Tests are important for identifying bugs early on. Ideally, we want to test for most tickets to make sure the website is working correctly. We will be using Vitest for the unit testing of our project.
First, let's check out Jira. If you click on your ticket, you should be brought to this screen. Click on the option for testing and select 'Requires Testing.'
After that, you can drag that ticket to the 'In Testing' column.
Now find the folder test within the main directory of the repo, and edit readme.test.ts. Add some code at the end similar to this but with your name instead of Houston:
test('Houston is on the README', () => {
expect(readMeText).toContain("Houston");
})Now here comes the actual testing! In the command line, execute the following command: npm run test. If you've written your name on the README, and your test is valid, then you should see all passes.
Make sure to commit your changes at this stage! Use 'test' to specify that you worked on a test in this commit.
Example Commit Message: "ORAKEI-3 test: Tested Houston was in the README"
Once you've finished your ticket, you can create a pull request8 (or PR) on GitHub. First, navigate to the Pull request tab on GitHub and click 'New Pull Request.'
This dialog box should pop up. Please select the branch you were working on.
Note: If you check Jira at this stage, you should now be able to see that the 'Branch' title on your ticket has now been renamed to Pull Request which is OPEN.
Once someone has reviewed your changes, they can approve the pull request by merging it. For our team, we want at least one other person than the person/people who developed on the branch to approve the pull request. This allows us to check for any possible coding mistakes or errors in the branch, through peer reviewing.
After your pull request has been reviewed and merged, you should now be able to see the changes on the ticket in Jira. If you hover over the pull request icon, it should now say MERGED.
Please move this ticket to the Done column.
Congrats!! You have successfully made changes to the repository! Houston is pleased with your work :)
- What is Git?
This is a version control system, used for tracking changes within a file system. It works through a repository (or "repo") containing all the project files and the revision history.
- What is Homebrew?
Homebrew is a package manager for MacOS and Linux to help install software directly from the command line.
- What is Astro?
It is a static site generator, or in other words, a framework that loads pre-built HTML and CSS. It is relatively new framework, designed for making content-heavy sites that run quickly and smoothly.
- What is NodeJS?
It is a JavaScript framework that allows JavaScript to be run on the web application's server side. It can handle requests from the browser and formulate some responses, such as an HTML page or CSS files. It is often used in a full-stack workflow with frameworks such as React, Vue, or, in our case, Astro.
- What is a ticket?
This is a task assigned to someone to compartmentalize development. It helps us prioritize tasks based on urgency or tags and gives us a clear picture of what parts of the program require work, are in progress, or are finished.
- What is Jira?
It's a system for tickets developed by Atlassian. Many Agile teams use Jira to manage workflow for task management.
- What is a branch?
It is a contained area of the repository where you can implement and test new features without directly modifying someone else's files.
- What is a pull request?
It is a proposal to merge one branch into another. Other developers can review the changes and make comments before taking those changes and merging them with another branch. We would want to pull request one branch into the main branch for most changes.
- Can I use GitHub Desktop to do most of this?
Yes, you are free to commit, pull and push in whatever way you see fit. This command line stuff is just good to know for any general project :)
Big Houston is watching you