Contributing

Treat ng-rewrite as main for now

TL;DR

1. Name your branch appropriately
   1. fix_issue-number_short-description-of-issue for bug fixes. Omit issue-number if there is no issue/ticket on GitHub for the bug
   2. feat_issue-number_feature-name for features. There should be an issue number for features.
2. Run npm run pre-commit before committing your code.
3. Push your changes up and open a PR to main
4. Once your changes have been approved they will be squashed into main

If you're new to development start here

Otherwise skip to Contribution Process

First off, welcome! This project was designed to help people learn about web development and working with a team. Please don't hesitate to contact me (the current maintainer of this repo) about this project. I'm here to help people learn and if I don't know the answer to your question then I'll help you find an answer.

Contribution Process

This process is a bit more formal than how your personal or school projects might be. This is meant to emulate a structure that you might encounter if you become a software developer. It might feel overly-complex and tedious, but to ensure this project endures we need to write things down. Part of the job is writing stuff down so the next person can understand what to do. Take the perspective of someone that has no clue what you've written or why you've done things. If someone can understand what and why you've done something before reading your code then that saves that person a lot of time and makes it easier to read your code.

Getting a Ticket

Take a look at the issues board and see if there's something unassigned that you'd like to work on. If you have questions or need support on what needs to be done, just ask. We will be monitoring the issues board so that you can start contributing as quickly as possible. If you're interested on working on an issue, leave a comment so that someone knows it has been taken. If you're not in the W3 committee yet, you won't be able to assign yourself to the issue. Once you have submitted your first feature, you'll be added to the W3 committee, so you can easily maintain it.

Starting Your Changes

Naming your branch

Whether you've forked the repo or are working directly on here, it helps to keep things tidy. Branches should use underscores for sections and hyphens for different words in the section. I'm partial to the following naming prefixes:

• fix_issue-number_short-description-of-issue: Fixes for bugs on the issues board. Omit issue number if there is no issue.

  e.g. fix_123_readme-wordwrap, just from the branch I know which issue number it is and what the issue roughly was

• feat_issue-number_feature-name

  e.g. feat_22_exam-bank, similar to above, we know it's a project or feature, which issue it's linked to and what the project roughly is

• rf_issue-number_refactor-name

  e.g. rf_456_updated-theme, similar to above, we know it's a refactor, which issue it's linked to and what area the refactor touched

Commands to create a branch locally:

# Update your local repository with the latest on remote
git fetch

# Make sure you're on `main` first
git switch origin main

# Create your branch
git checkout -b <name-of-local-branch>

What is branching?

This will be a very short explanation, since you could teach an entire class on git (which, honestly, they should do).

When you work with git, everything exists on a branch. Think of a git repository as a tree; main is the "trunk" (look up trunk-based development) and everyone's work "branches" off of it. You branch is a snapshot of wherever you branched from (it doesn't have to be main) and allows you to do your work without anyone else's changes affecting you. Imagine a bunch of people typing on the same line in a Google doc at once; that's what Git is trying to prevent.

Before You Commit

Ensure code style is consistent with the rest of the repo

To ensure our code has consistent formatting and style, I've set up a few npm commands you should run before pushing up your changes. These libraries are: Prettier and ESLint

What is ESLint

ESLint is something called a "linter". It's a tool that analyzes your code and makes sure you're it's structurally sound. If you've used a code editor and seen coloured squiggles then you've used a linter before. It will tell you that there's a syntax error, like having the wrong number of parameters in a function call, or a there's a code style rule that you're breaking, like declaring a variable that's not used.

ESLint is used in this project to enforce stricter code standards. Stuff like creating empty classes or not specifying a return type on a function, are all things that will not stop TypeScript from getting compiled, but it makes our code easier to read for others. Over time, we may need to add more rules to make sure the codebase doesn't end up becoming a mess.

Most of the major code editors/IDEs have ways to integrate with ESLint, so that you will receive these errors while you code.

What is Prettier?

Prettier is a code formatter for a bunch of different languages. You can specify certain styles that Prettier will automatically change for you when it's run, such as adding semi-colons to the end of statements, changing double-quotes to single-quotes and how big your indents need to be for certain files.

Most of the major code editors/IDEs have ways to support a .prettierrc, so you can format your code while you write or on save.

Eventually there will be some checks that will block you from getting your changes reviewed until your code is properly formatted. I may add more checks in the future. You can see the ESLint rules I've set up in eslint.config.mjs. You can view the configuration for Prettier in .pretterrc.

You can find the npm commands in package.json under scripts. The commands are:

npm run lint   # Runs ESLint to check for code that breaks certain rules
npm run format # Runs Prettier to format your code

You can run them both using:

npm run pre-commit # Runs ESLint and then Prettier

If ESLint gives you errors, try and address them. Don't use eslint-disable unless there's no other way around something. If you're not sure about something just ask!

Now you're ready to commit your code!

Submitting your changes for review

Test your changes locally with main

Before pushing your code up, make sure you've rebased your branch off main and test everything again. It's your responsibility to resolve any merge conflicts that may arise. If you're working on the main site that means the app compiles, there are no npm run pre-commit errors and your feature works exactly how it should. If you're doing work on the static sites, there is no compilation errors, so just make sure your site still works.

git fetch # Update your local repository with any changes on remote
git rebase origin main # Rebase your changes onto the latest main changes

You can push your code up at this point.

git push origin <name-of-remote-branch>

What is a merge conflict and why am I responsible for it?

A merge conflict happens when the incoming branch can't apply its changes to the target branch. This happens when a commit on one branch makes changes to a line in a file and a commit on the other branch also makes a change at the exact same place. Git doesn't know which change should go here so it stops and asks you what to do. This video explains it pretty well https://www.youtube.com/watch?v=HosPml1qkrg.

Remember, when you created your branch, it was a snapshot of whatever branch you made it from. That means if the original branch gets updated your branch will be unaware of these changes. Rebasing your branch onto main means you apply all of the commits that are on your branch--but not on main--one-by-one onto main until it either fails (meaning there's a conflict) or it succeeds (meaning your changes were applied cleanly). Just because your changes applied cleanly that doesn't mean your feature works still works! That's why you need to test it you rebase.

If you receive a merge conflict when you open a pull request it's not the end of the world! Merge conflicts are inevitable and sometimes resolving them is super easy! The video explains how to resolve merge conflicts in VSCode, but the principle is the same everywhere: tell git what the code should look like.

A good trick to avoid conflicts is by regularly syncing your branch with whatever it was based off of. This is either done by regularly rebasing your branch off its original branch(do this if you branch has not been pushed to remote) or by merging your branch with the original branch (do this if you have pushed your branch to GitHub already).

Rebasing vs merging

Another way of thinking about your branch is it's a timeline of events, the events being your commits. Merging, at a high level, is simple, git takes a target branch (the branch you're on) and a source branch (the branch you declare in the command) and it attempts to bring all their changes together. How does git know the order of events the timeline should follow? Git has a few strategies, but it can get complicated very quickly, so I'll defer you to this article if you want to know more. The end product of a merge looks different based on the strategy, but in the end you'll have a branch that contains all the changes both branches had.

Rebasing is a different concept and it doesn't necessarily require you to work with multiple branches. Rebasing let's you rewrite "history". Using the timeline analogy, this means you can change the order events happened in. You can change commit messages. You can add changes to an existing commit or combine two commits together. Rebasing is very powerful, but it can also cause issues with between your local and remote branches. This is why I suggest not rebasing if your branch has already been uploaded; if the two branches (local and remote) have conflicting histories then pushing will fail.

When we rebase our changes (branch B) onto the original (branch A), here is what (roughly) happens:

1. Branch B (our branch) is reset to the last common ancestor, so that the branches become identical at that point in time
2. We "replay" all of the commits branch A has had since this last common ancestor
3. Then we "replay" all of branch B's commits on top

The end result is a branch that looks like: [common history] - [branch A's different commits] - [branch B's different commits]

So then why do we rebase when testing our changes on main? By rebasing your changes onto main you find out two things: are your changes compatible with main right now, and did someone else change something that is incompatible with your code? This is why you should test afterwards, you might use a function that was changed and now your whole feature doesn't work.

Opening a pull request

1. Go to the csss-site-frontend. If you've forked the repo you can do this a number of ways
2. Open a pull request (PR) on GitHub with the base as main and compare as your branch.

Open a PR on GitHub

Request a review

When opening the PR, make sure request a review from someone in the W3 committee. If you don't know who to request, the person who maintains that feature is a good choice. If you don't know that then request a review from the Webmaster.

Someone will review your code and either ask you to make changes or approve it. Once approved, your code will be squashed, so write a well-written description of your changes. When the changes are squashed, your smaller commits will be combined together into one big commit, so make sure to provide anything that could be important in the PR message, as that is what the log on git will show. If your code is tied to an issue, add a closing keyword to automatically close the issue once your PR is merged in. If your changes close multiple issues make sure to mention all of them.

Closing keywords

For a feature:

Feature: Exam Bank
closes #123

Description:
Talk about what was added and who it's for.
e.g. Added an exam bank which ..., which is intended to be used for students in CMPT courses.

Features:
* list
* of
* features
* e.g. Added a new tab in the activity: Exam bank
* e.g. Users can view old exams, by year, class and semester

For a bug fix:

Fix: Word wrap on header in README page
closes #456

Issue(s):
Describe what the bug was.
e.g. On the README page, the typed in message "Computing Science Student Society" was wrapping on letters rather than words.

Root cause:
Explain the root cause of the issue.
e.g. Since the animation used GSAP's split by chars feature, each individual letter was its own inline-block, which means word wrapping wouldn't work since they were all separate divs.

Fix:
Describe your solution.
e.g. Added reverted the letters back to a single div using `split.revert()` once the animation has completed.

(optional) Future issues:
If you foresee your fix causing an issue in the future mention it here. 
If it's something we'll need to address then we can open another issue to address this one.