Dos and don'ts

Document Creation: 7 May, 2024. Last Edited: 10 July, 2024. Authors: Leesa Ward.

Summary of things to do

• Fork the existing repositories for the project(s) you need to work on to your own GitHub account, and do your work in that codebase.
• Create a branch in your fork for each piece of work.
• Use React for your front-end work, with the supporting tools and libraries described in this documentation such as TypeScript, Styled Components and React Router.
• Use the provided generator script to create new components.
• Use TypeScript with a type (or interface) in place of PropTypes.
• Use React function components in the first instance, or migrate if you have already developed a class component.
• Raise small pull requests, often.
• Keep pull requests limited to a single feature, change, or bugfix each.

Common mistakes and how to avoid them

Where to do your work

Mistake	Creating your own repository and start creating a website/app from scratch.
Why it's a mistake	These are team projects designed to be handed over and worked on by multiple capstone cohorts across trimesters. Multiple students creating new websites/apps from scratch means duplicated work, reduced collaboration, and inconsistency that negatively impacts our projects' longevity.
What to do instead	Fork the existing repositories for the project(s) you need to work on to your own GitHub account, and do your work in that codebase.

Mistake	Assuming you cannot work on a company repo if you can't create a branch, so not doing any work or starting a new website/app from scratch.
Why it's a mistake	For ease of admin across trimesters, direct write access is limited to project leaders, mentors, and selected students who are experienced with Git and/or leading specific pieces of work. All students can fork the company repositories, so this is no barrier to beginning work.
What to do instead	Fork the repository and create a branch in your fork for each piece of work.

Mistake	Adding a new folder with a separate React app to a repository.
Why it's a mistake	This is a team project. We are all working on the same app(s), and for separation of concerns and effective collaboration there must only be one app in each repository.
What to do instead	Follow the guides in this documentation website to set up and work on the app that has already been started.

Tech Stack

Mistake	Using PropTypes in React.
Why it's a mistake	PropTypes are deprecated and their use would block future upgrades.
What to do instead	Use TypeScript with a type (or interface) in place of PropTypes. The Redback UI repository has some examples you may find helpful, and using the generator for new components in Redback projects will set up the boilerplate for this for you.

Mistake	Using class components in React.
Why it's a mistake	There may be some edge cases where class components are still appropriate and they are not officially deprecated, but they are considered to be a legacy API and are not recommended for new components.
What to do instead	Use function components in the first instance, or migrate if you have already developed a class component. For new components in a Redback project, using the generator script will set up the boilerplate for a function component for you.

Mistake	Not using React, and writing your code in vanilla HTML/CSS/JS or using another framework/library.
Why it's a mistake	This is more of a recommendation of something to avoid than an outright error. Ultimately to be accepted into the projects, code needs to be compatible, so you're creating work for yourself if you build something that will need to be refactored later. If you are doing this because you don't know React, that's understandable and a valid choice so long as you understand that you will also need to make it work in React. Please also be aware that leaders and mentors may not have capacity to provide detailed feedback on code that is not PR-ready.
What to do instead	Consider this work a prototype - it can be shown in team meetings and used as a starting point or proof-of-concept (but do not raise pull requests with this code). Set aside some time to upskill/cross-skill in React and the other tools/libraries in our tech stack.

How to submit your work

Mistake	Doing a lot of work over a long time in a single branch, then raising one huge pull request - often late in the trimester.
Why it's a mistake	The larger the PR, the more complex it is to review, meaning that: the review -> feedback -> changes -> re-review loop takes longer, so the whole team and project(s) benefitting from your contribution is delayed mistakes and valuable technical feedback are more likely to be missed in reviews it is harder to identify and fix merge conflicts, increasing the time you spend on tedious contributions may not be merged at all because time runs out. Many team members submitting large PRs late in the trimester exacerbates this due to the increased workload on leaders and mentors.
What to do instead	Raise small pull requests, often. For example, rather than waiting until you have completed a whole webpage, complete one component and submit a PR for that, then another for the next one, etc.

Mistake	Sending code to project leaders or mentors directly.
Why it's a mistake	This is an impractical way to review code and provide feedback. Plus, all code submissions need to go through the pull request process regardless of any conversations that go on through other channels.
What to do instead	Raise a pull request to have your code reviewed. If it is a work-in progress you want feedback on, you can mark the PR as a draft and note in the title/description that it's a work-in-progress. Please see the Submitting Code page for more information.

Mistake	Raising a pull request in the template repo, when it should be raised in a team project repo.
Why it's a mistake	Because the team project repositories are forked from the template, if you follow the link shown in your terminal after you push your commit to go to GitHub and raise a PR, it may have that as the target.
What to do instead	In that pull request creation screen, check the target and ensure your project repository is selected, not the template.