2022 Reflections

To give a quick rundown on the status of Circles and the things we did over the past year:

• released our MVP which includes the degree wizard, course selector and term planner

• supported several degrees after MVP deployment

• later released progression checker (and dark mode)

• QOL improvements

• refactoring and improvement to the Circles codebase

As of the time when writing this, these are the features that are currently being worked on and will hopefully be released by the end of the year:

• graphical selector page

• auto timetabling

• user migration to the backend

Planning and setting expectations

• when you set a timeline, please make sure its legit. This means that you have split up the task, talked to your team about it, etc.

• Set deadline dates when needed if progress of subcom becomes stagnant so the expectation is clear.

• Check up on your subcom invidually on a regular basis. I feel this is a better way to gauge progress on their tickets and if they need help between each retro/meeting.

• Make sure you follow up on your subcom and held them accountable for their work + the deadlines they give.

Team

Subcom Recruitment

I just want to say as a disclaimer that choosing your subcom should be entirely your choice and what you believed works best for the team. But here are my (@Gabriel Ting (Unlicensed)) thoughts when choosing subcom members, so take it with a grain of salt.

• Decide whether if you want a very technical/cracked team or a team that has social vibes. Although, we join projects to code, it is important to consider if you want the social aspect that comes along with it.

• Try to be weary of very cracked/career driven individuals during subcom recruitment. If they know XYZ but have alot of commitments at the same time, consider them with a grain of salt since from past experiences shows these type of people leaving projects/going AFK soon after. Unless you reckon they are a good fit for the team + seems very committed/interested in the project + someone you can get along, take this into consideration when choosing

• Define what would you want your team to be! Do you want to have subcom with the technical experience? Do you want your team to have the social dynamics? A mix of both? It’s entirely up to you. For me, I tend to also do a vibe check just to see if they fit the team I want + seem interested. Having a face to face call really helps sus out the applicant.

  • From experience, people who you can vibe well + seems very interested in the project often do more work than a person who just has the technical experience.

NOTE: A thing to note is that with subcom, this is a volunteering experience meaning that subcom have other priorities besides projects (which is fair)! This tend to mean that most likely, you probably have the most passion to do meet your vision over the others. Keep this in mind as at times, your subcom may be doing the bare minimum in terms of progress which can greatly affect the speed that you want your featured to be developed.

Team bonding

• In some places, larger events (i.e. project wide events) got in the way - prioritise your own events, fuck larger events if it comes down to it

  • this is because larger events are great in general, but your internal team bonding shouldn't be compromised for this

• Push for in person meetings. I know this is hard, but just make it an expectation early. This really helps setting the tone for team bonding as after the inperson meeting, you could do some activities (i.e. dinner)

• Have periodic in person catchups like dinners or coastal walks. The frontend team usually has hangouts once every 2-3 weeks and it usually kept engagement up for the team to do work.

• Depeding on the team, if no one seems interested in participating in online social events (i.e. games night), dont do it! Really see if your team prefers in person hangouts or online.

To split FE and BE, or keep it as one…

In 2022, Circles were split into seperate FE and BE teams with @Gabriel Ting (Unlicensed) leading the FE team (6 members) and @Peter Derias (Unlicensed) leading the BE team (~8 members). In essence, there were two ‘mini’ subcoms within Circles.

There are a few advantages to the split

1. it attracts people that hate FE (or vice versa) - these people are generally giga-brains. You do want them usually.

2. it reduces the size of your meetings. The length of your meetings is proportional to the number of participants. Since Circles needs a large team, it is in some cases useful. Also, it allows each team to have meetings relevant to their work.

There are however some heavy drawbacks

1. It can torpedo good design, because the person that wants to implement something might decide to do it on the side they are from, not from the side where it is best to implement it. This ranges from small things like making fixes to the output of the BE in the FE instead of the route itself, to larger structural issues like progression checker’s issues with double counting in the beginning.

2. It leads to people that are unfamiliar with the other side. When you ask an FE person to implement a tiny route, or a BE person to add a button, catastrophe occurs. Ideally you want people flexible enough to be able to be responsible for a feature. Features will rarely only involve one component.

3. It leads to the issues with having only 1 lead for each side, to a lesser extent to last year. With 1 lead, you need to be on as fuck. It’s intense, especially when you are trying to onboard. Now, you can still hop on to social stuff from each other’s teams, but it’s not always that easy when you guys don’t attend the same meetings.

@Peter Derias (Unlicensed) and @Gabriel Ting (Unlicensed) would probably suggest that this split should be gone by next year. It was useful as a product of its time, because it had the advantage of:

1. not needing to teach first years fullstack

2. getting MVPs for the FE and BE to show in a reasonable time scale without having to get 15 people on the same page.

These issues have become less relevant this year, and will vanish by next year when our offerings all enter release.

As a note, if you decide to keep FE and BE together, I would recommend shrinking the team sizes from what we had this year so it becomes more manageable.

Technical

• Push for quality, always.

  • Testing. Do it. I know its annoying, but it reduces the amount of bug cards that need to come in, and take the edge off deployments. Me and Sano had many sleepless nights as we released our stuff in the beginning of the year.

  • Use good tools. We have migrated to typescript, vite, mypy, and improved the general code quality tremendously. I promise you, this sweat paid dividends. The FE team’s speed skyrocketed when they moved to TS, and the BE team’s code quality improved massively, as well as had a speed uplift.

  • People want to have fun working on the code base. Having to fix someone else’s bugs, working with a shitty tool, and wrestling with documentation are not fun things to do. anything that gets in the way of them having fun working on your project (environment shit included) is kryptonite, and is a great way to disollusion your subcom. Any issues they have with this aspect of the project should have swift, decisive remedies.

Frontend

• Make sure you wrap your head around our stuff quickly. When you come in to the role, you need to become the god of this codebase before your subcom even arrives. FE god, you need to understand:

  • redux

  • typescript

  • how we do routing

  • How we manage warnings, and suppression

  • vite configs

  • drag-n-drop

  • jest/vitest + react component library (RTL) for testing

Refactoring… Rewriting… the FE codebase

When I first joined Circles FE, the codebase looks so much different compared to what it is today. This is because the FE codebase has seen some major uplifting over the past year in an effort to improve code quality. For context, in 2021, the FE team comprised of mostly new react developers which at the time, established some of the major features that is still used today. However, due to the rapid development of an MVP + react beginners working on the codebase, it came at the expense of code quality and style.

As such, the frontend repo as seen these uplift efforts come into play:

• setting up eslint

• reorganising the component file structure

• moving from css/less over styled components

• converting from javascript to typescript

These refactors were all essential to improve the overall dev environment of Circles and now we are at a stage where the FE codebase is imo a very good codebase to work with! From here, I don’t see the FE codebase to have this major of a refactor but if it comes down to it, here are some advice:

1. consider if the refactoring is essential and would provide a better outcome once it has been done. With these refactoring efforts, there were certain outcomes that I wanted to hit. i.e. moving from css to styled component ensured out styles were encapsulated and made custom styling much easier, typescript for types, etc. We didn’t refactor just for the sake of refactoring!

2. how would this refactoring effort impact the others? i.e. merge conflicts. Try to do it when there it wouldn’t affect anyone’s development

Due to the strides of the refactoring efforts by the 2022 team, I would advice you consider whether the refactoring efforts are needed from here on. This is mainly the fact that the FE codebase is of high quality and does not really need any more uplifts at this point. It is important to measure whether any refactoring efforts is worth speding time on over developing any new features.

Note: I (@Peter Derias (Unlicensed)) would reccomend that if you are ever considering refactoring, or some other large scale CI/CD or tooling project, that you do it yourself. This does 2 things:

1. it makes the fallout of this lessened. Having multiple subcom distracted by this type of stuff makes it very hard to keep track of the codebase.

2. You have the utmost confidence in what you write, but your team doesnt. These types of cards are very hard to give to subcom, because naturally, you will need to explore yourself to come to a pattern. Unless that member is cracked (cracked members do exist, and i can think of them off the top of my head - you will know where the exceptions are) they won’t have the gusto or motivation that you do.

Backend

• Make sure you wrap your head around our stuff quickly. When you come in to the role, you need to become the god of this codebase before your subcom even arrives. BE god, you need to understand:

  • mypy (static type checker) as well as TypedDicts. These help tremendously with IDE hints. Please make sure they are used to their largest extent.

  • OR tools. you don’t need to fully get it, but you will need to kinda get it. Have a look at my documentation.

  • User migration, how we do it, and what we are storing and how.

  • Conditions parsing (obviously)

  • Maturity requirements (you should think about how to expand this for other degree requirements)

refactoring

I did little refactoring this year, but did a lot of data munging in secret. I never really switched tools, but ive probably redesigned the api at least twice to improve it (it probably needs one last one after we do the BE migration when you’ve got time, but dont tell FE that). I reccomend that you stick to this type of refactoring. You can (for example):

1. improve tokenisation to take some burden off create.py

2. slightly change the API endpoint names to be more logically formatted

3. work on improving the interface between maturity requirements and the rest of the codebase.

But i beg you - DON'T REWRITE!!!!!! I know there have been memes about this a lot. but please, they are just memes. keep it at that.

There are a few common complaints that I have encountered and do agree with. But, I scencirely believe that it is due to our use of our tools, and not the tools themselves that are a problem.

1. the problem with types → there are many places where stronger type checking than the type provided by python would be benefical. I know that it sucks that mypy isnt acutally that strict, but what you need to do is use mypy to its full potential. You need to abuse typedDicts, you need to define types more strictly, and you need to create better dataclasses that can store data in a more sane way. There is a reason I moved to python 3.10. Use the new stuff!!!! Python’s new stuff is a leap forward in type safety. Research it and incorporate it into the codebase. I started this with mypy and started introducing dataclasses in my autoplanning code, but ran out of time. Use this as an example!

2. tooling around python generally → yes, installing python 3.10 is sometimes miserable, and people suck at managing their python installs and packages. That is what venv and pyenv is for. Use them. Also, with the release of ubuntu 22.04, its become easier for ppl to update python - they just need to update their ubuntu to the latest LTS. Make them do it.

3. Speed. This is the dumbest one. Our backend is never the bottleneck. The FE is always slower. chill out. I dont think you will ever run into a big enough bottleneck where a speed uplift would benefit the end user. Also, dont mention OR tools becoming faster. There is only a thin python wrapper around their implementation.

TLDR: dont rewrite in rust, because OR tools doesnt have a rust implementation. (it does, but the wrapper sucks even worse than the python one, and the python one is already miserable). Dont rewrite in java, because you just suggested to write something in java (????).

What’s next for Circles?

2022 was all about getting the MVP ready and establishing the core userflow down. There are still features that we are working on that may not be finished until early 2023, mainly data migration to the BE. But otherwise, I feel that Circles may reach its maintainence stage next year. That doesn’t neccessarily mean that there’s nothing left to develop Circles! It’s just expanding on what we have already!