Introduction
For the starter ticket, everyone will be adding their name to the credits page! This document will take you step by step through the entire process: creating your ticket, creating your branch, making changes, making commits, pushing changes, and creating a pull request. Once you have made the pull request and we’ve reviewed it and merged it, then you will be assigned a Tech Lead and can start working on tickets from our project board.
Note: The credits page is hidden. There is no button to get to it. To navigate to it, you have to go to the link manually by going to localhost:3000/credits.
Create the Ticket
Note: If your GitHub account has not been added to the repository yet, message your GitHub username in #software_env-setup to ask for access.
In the repository, you will see a tab called Issues. Click on this tab and then click the green "New Issue" button in the top right of the screen. From there, select the "Task" option by clicking "Get Started". This will open the template for a “Task” ticket. Feel free to explore the other tempaltes.
Name the issue: <Your First and Last Name> - Credits. For example, Anthony Bernardi - Credits. Your description should be something along the lines of: "Giving myself credit for the amazing developing work I will be doing at NER!" Your acceptance criteria should be something along the lines of: "See my name in my favorite color on the credits page." Your Proposed solution should be something along the lines of: "Add my name and favorite color to the "names" array in the CreditsPage.tsx file". You can leave the mocks section empty.
On the righthand side, click on Assignees and find your GitHub username and select it. Then click on labels and choose the credits label. When you’re done, the page should look like this:
If it does, click on Submit New Issue. Congratulations! You've just made your first ticket in Finishline!
Create a branch
Once you’ve created your issue, you will now create a branch where you will work on your issue. In your command line, navigate to your local FinishLine project (view environment setup if you’re unsure how to get there). If you enter the command git branch, it will show you the branches available and, highlighted in green, is the current branch you are on. You should be on develop, if not, run the command git checkout -b develop. Then run git pull to download all the latest changes from develop.
From here, create a new branch by running the command git branch #yourissuenumber-yourname-credits. The issue number is the number that appears right after the title of your issue on its page. For example, your branch name should be something like #546-AnthonyBernardi-credits. It is very important that you add your issue number to the beginning of your branch every time you create a new branch. Congratulations again! You've created your first branch in FinishLine and can now open it in VSCode or your preferred IDE to start coding!
Code
Open up the folder in VSCode as instructed by the environment setup doc. Follow the contributor guide for specific coding practices. For this ticket, the file you will be editing is under the path src/frontend/src/pages/CreditsPage/CreditsPage.tsx. Click around through the folders and open up that file. Feel free to take a look around at other files and folders to see the code you will be getting familiar with for the rest of the semester!
This file is a TypeScript React file, which allows it to use normal TypeScript as well as HTML tags. Read through the file and try to get a general understanding (don’t worry if it doesn’t make any sense, our React Learning Session is next Monday). In this file, your goal is to find the "names" array and add a new entry containing your name and favorite color to the end of it!
TypeScript is built off of JavaScript, which uses JSON. Here’s a 1 minute video explaining how JSON works. Here’s a quick article explaining the basics. In TypeScript, we are able to add a type annotation to a JSON object to enforce the right type. A declaration of a variable might look like this:
const cat: { name: string; age: number } = { name: 'Lucky', age: 13 };
In this example, const means that this is a constant and won’t be reassigned. cat is the name of the variable. The : after cat and the JSON after it is a TypeScript feature that tells us the type of cat. In this case, cat is an object with a key name that is a string and a key age that is a number. Finally, we assign cat to a value using =. We make it an object where the name is the string Lucky and the age is 13. Try putting the above line in the file we’re working on and change age to be 'five'. Do you get an error? What does it say and Why?
Using the above information, you should be able to add another entry to the names array in the file.
Once you’re done, save the file. To view your changes, go to your terminal and run yarn install and then yarn start. This will start the website at localhost:3000. Go to your browser and enter the url localhost:3000/credits. If you get stuck along the way make sure to ask any questions in slack!
Committing Your Code
Once you’ve made the necessary changes and are ready to submit what you have for review, go back into your command line and run the command git add . which will save all the changes you've made. Then run git commit -m ‘#YourIssueNumber Added my name to credits'. For example, #546: added my name to the credits page. Again, the # is important so that GitHub recognizes that you’re working on your issue.
Once you've committed your work, you must push it to the remote site by entering git push. You may need to run git push --set-upstream origin [branch name] as instructed by the git CLI if the branch does not already exist in the GitHub repo and only exists on your local computer.
Creating a Pull Request
Its time to create a Pull Request (PR) so that your code can be reviewed. Go to the repository and select the “Pull Requests” tab. From there, select “New pull request” and make sure that “base” is “develop” and “compare” is the branch you’ve created. Once you’ve selected your branch to compare, select “Create Pull Request.”
For your title you can leave it as the branch name if you’ve properly named it. For the changes, say what you’ve changed! If you struggled at all, let us know in the notes section! We won’t be using the test cases section for this ticket so you can delete it, but if you had written any complex code that needed testing, make sure to show the results here. For screenshots, make sure to take one of the screen when its fill the entire screen, and another one where you make it as small as possible.
On mac, the command to take a screen shot is command+shift+4, on windows its the windows logo key+shift+s. Drag the screen shot into the screen shot section and delete the filler text.
You can remove the Todo section as well since there’s nothing left todo. Then finally go over the check list and make sure you’ve completed everything.
On the right side of the screen you will see an option to request a reviewer, you can select any of the tech leads or Anthony. Make sure to assign yourself under the assignee section (just like on the issue page).
Finally at the bottom of your PR you will see “closes #”, enter your issue number next to the #. For example, closes #546. Finally, select "Create Pull Request" and now you've finished! You will know you've succeeded if on the right side panel under "development", theres a link to your ticket (if there isn’t, you can do it manually).
Wait for somebody to review your code, and if they have any comments make sure to make the changes in your code, and make a new commit with those changes, following the same rules as mentioned before (you do not need to create a new pull request).
Resources
For our guidelines on how to contribute to the repo, see the Software Contributor Guide.
For some resources on Git, see the Software Learning Resources page.