Read-Me documentation update

[Capyblapy]

Updated the Read Me to include repo information and goal of the project.

[dawilson9]

As a readme for the new repo this is fine (although I would pass it through a spell-checker before committing). When we last chatted about git documentation, I guess I didn't make myself clear. What I was suggesting is that the readme in the main robot_code_2026 (and earlier) repos should explain our git use strategy - how branches are used, our PR expectations (and whether or not we even use PRs - I would vote for not using them), and basic directory structure so that folks working on examples or prototypes would know how they should be handled. I feel very strongly that these should be inside a single repo and that we should not create new repos for every side project we want to work on.

[Capyblapy]

For the first point of repo specific documentation, I will run it through a spellchecker and create another commit.

To the point of the main repo documentation, before we do this we should decide how we handle our github and repo workflow. It seems that I am in the opposite opinion of you, where I believe that we should have one repo for one project and that PR's should be used to ensure that code which is being used as a final product and may be looked back on in future years are "up to standards" (Clear value names, documentation, etc). PR's also provide a clear paper trail in the history of when we merge features together and make potentially breaking changes.

[dawilson9]

You get to choose since mentors are only intended to provide guidance but here's my opinion based on 40 years of doing software development in small, medium and large teams.

The main goals of a source code control system are (1) to provide a central repository from which all team members can access code, (2) to prevent conflicting changes and maintain change history to allow changes to be backed out if necessary and (3) to ensure that the source code backed up and safe from disasters affecting any given developer's system. These are all vital and every source code control system and use model makes use of them. On top of these, however, there are layers of process added which create work for developers. The more critical the project and the mode developers involved, generally, the more process layers and the more strict the process must be.

The questions we need to answer here are:

(a) How do we use git repos and branches to store our project source code over multiple years?
(b) What's an appropriate level of process to impose given the kinds of projects we're working on?

How should we use GIT?

We currently create a new repo per year and you seem keen to create side repos for experimental projects. I very strongly suggest that this is the wrong model and that we should have a single repo for all code for all years, arranging the repo structure to accommodate this, likely with year-specific top-level directories and, within those, separate trees for competition code, examples, prototype projects, etc. There may be isolated cases where we want a separate repo but these will be unusual and should be avoided.

In my entire career, the single common repo model has been the only common thing in all the different code control models I've used. The single repo can either be team-specific or company wide but teams don't spread their code across multiple repos except in cases were access control comes into play and you need to share a subset of code with some team that shouldn't be allowed to see everything. We don't have that problem since all of our code is pubic.

Using a single repo means that you always have access to all code for all projects. This makes code sharing very easy and saves people from having to search through a bunch of different trees to find something they may be looking for.

Under a single repo, you most definitely need a branching model too that allows for feature development and an easy way to find the latest, tested code. Again, there are many different models used here, some appropriate for small projects like ours and others more suited to large projects. I'll discuss my suggestions regarding branching below when I talk about process.

What level of process is appropriate?

By "process", I mean the "paperwork" associated with using the source code repo. This covers problem reporting, branching, CI (continuous integration) testing, code reviews, push requests, etc. The stricter the process you adopt, the "safer" your system should be but the more time you spend doing work to support that process (writing problem reports, updating documentation, reviewing PRs, merging branches, etc.).

As a mentor I hope to give you a flavor of the processes used in commercial software development projects but, at the same time, I don't want us to adopt a very process-heavy model that isn't appropriate for the small projects we are working on (yes, our software project is VERY small by industrial standards even though there's a lot of work involved). I believe you should be aware of different models but we shouldn't adopt something intended for a 200 person team working on 5 million lines of code which would cost us 30 minutes per commit to jump through all the mandated hoops.

Given this, let's talk about branching and commit policies.

Branches are enormously useful for (1) developing new features before they are ready to integrate into a larger project and (2) to control versioned releases. Adding new branches should be done carefully, though, since a branch is another effective way to hide code. Branches should not be used to hold whole projects that are never intended to be merged to any release or integration branch, for example.

Over the last 40 years, the model that I've used in pretty much all projects involves a stable branch (main/master) containing tested code and documentation, and one or more development and feature branches. The development branch or its equivalent contains the latest integrated code that folks are working on. It's expected to build and most features are working but it's not necessarily fully tested. Day-to-day commits go into that branch and changes are merged to the main branch as the full system is tested. Additional branches are owned by individual developers as they work on specific features (assuming those features are large and require the use of a branch - small changes are mostly pushed directly to the development branch). Developers are responsible for deciding when to merge feature branches to development themselves.
At no point in my career have I worked on a team that required PRs. The heaviest process I've used required that every commit was tied to a problem number via a link in the commit comment.

I would suggest sticking with a light process where we allow free commits to development and feature branches (discouraging the creating of new branches if possible). If folks are desperate to use PRs, use them only for merges from development to main (but I would suggest not doing this and relying on communication and professional responsibility instead, allowing any developer to merge but requiring that they meet some testing standard before they do this and that all merges are accompanied by comprehensive commit comments explaining what changed).

Overall, the goal is to adopt a process that gives us the benefit of the source code control system without slowing down the development process to a point where it becomes onerous to follow. If we are process-heavy, I guarantee that the process will break and folks won't use it, resulting in a mess. Think of the situation at competitions and imagine how annoying a strict process with lots of rules to follow would be in that environment. K.I.S.S. as they say.

[jee7s]

I recommend we use a simple feature branch workflow rather than this flow, which is similar to gitflow. Our repos are too short lived and our processes are so lightweight that distinguishing 'main' and 'develop' is of little value.

[jee7s]

Glad to see we are thinking about process. I agree with @dawilson9 on the single repo approach and I've left a comment regarding a simplified workflow.