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: ‘Boo', age: 17 }
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!
Comitting Your Code
Once you’ve completed your ticket and are ready to submit what you have for review, go back into your command line, make sure you are still on the right branch by running git branch, 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' Once you've committed your work, you must push it to the remote site by entering git push.
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, but if you had written any complex code that needed testing, make sure to show the results here, but for now you can delete this entire section. 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’ve completed the ticket so theres nothing left todo! You can remove this section as well. 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, then make sure to assign yourself under the assignee section. Finally at the bottom of your PR you will see “closes #”, enter your issue number next to the #. You will know you’ve succeeded if on the right side panel under “development”, theres a link to your ticket. Finally, select “Create Pull Request” and now you’ve finished! 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).
Handling Merge Conflicts
With everyone working on the same piece of code, you are almost guaranteed to encounter a merge conflict. Github will tell you if your branch has merge conflicts in your PR just beneath where it shows you whether or not you’ve passed your tests. If you do, in your local Finishline directory, run the command git merge develop, this will bring all the changes from develop into your branch and allow you to resolve your merge conflicts. In VSCode, where you have merge conflicts, you will be presented the option to "accept incoming", "accept current", or "accept both". You will most likely simply want to press "accept both", and that will hopefully resolve your conflict. You can then commit your changes by following the steps in "Submitting your code". Check your pull request to make sure the merge conflicts are gone, and then your all set!