Ucalgary_Baja/Baja-Charter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Uploaded Charter and Software Related Items

Browse Source
This commit is contained in:
darkicewolf50 2025-02-02 11:28:06 -07:00
commit fb3c55f1c5
2 changed files with 1138 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

755
Baja Software Charter.md Normal file
View File

@ -0,0 +1,755 @@
# Software Subteam in Baja
Developed in part by Brock
Competition Season Written in 2024 - 2025
## Overview of Whole Club
Based on the 2018 Baja Charter
UCalgary Baja is a performance team. We are committed to designing, building, and completing an off-road vehicle. Our intent is to develop the best vehicle possible and place it in the top 10 in competition. To achieve this goal UCalgary Baja enlists high-performing, committed and passionate individuals.
UCalgary Baja is a team comprised of students who want to expand and apply their knowledge of engineering principles and develop a skill set to aid in their development as engineers. It is important to note that UCalgary Baja does not exclusively recruit “car enthusiasts”. UCalgary Baja provides you with opportunities to realize your developmental aspirations.
UCalgary Baja believes in the mantra You get out what you put in. We’re excited to have you and your unique individual skills and experience contributing to the mission of creating the best car possible. The lessons you will learn and the accomplishments you will make are up to you, and UCalgary Baja will gladly work alongside you to push you to your limits and beyond.
## How does Software Fit in?
### Purpose
#### What is Software at Baja
Software in Baja currently means the support team of the club through the development of software applications. This could be done by the use of our cloud to make running/operating the club cheaper, why pay for something when it can remade for free. Such projects include the BajaCloud which in itself contains the interview booking backend and the reimbursement backend. This does not mean the software can transform into a simulation, embedded programming team, data collection/transformation or cloud team. The options are up to what the lead decides/imagines best.
### The Future of Software
The Future of Software is in lidar track data collection and inputting into BEAMNG.drive and create a simulation of the car every year with current tracks, I hope that the team uploads the car cad/model and track to Steam and releases it for free.
The future could also be in embedded/testing systems on the physical car, as of right now I would suggest rust as a primary language due to its speed, safety and high-level features such as a formatter, inferring and package manager (crates).
### Core Beliefs of Software
Repeated again for Highlighting
```
You get out what you put in.
```
If you don't show up and do work you don't learn anything from more Senior Members.
```
Communication both written and oral is based on signals or promises with the receiving party obtaining those signals and promises.
```
This also applies to coding, particularly in HTTP requests.
### Who to Recruit especially in Software
This is directly taken from the 2018 Baja Charter and repeated again to highlight its importance.
```
It is important to note that UCalgary Baja does not exclusively recruit “car enthusiasts”. UCalgary Baja provides you with opportunities to realize your developmental aspirations.
```
I would look for anyone who is passoinate or wants to learn in their appilcation, this shows that they want to do software, you will be able to tell if it is a mech application, use your judgement to determine if you want the mech applicant
## What do you get out of Baja
This is based on the 2018 Baja charter
### Camaraderie & Lasting Friendships
UCalgary Baja is a team where strong, long-lasting friendships are made. This camaraderie aids in both successful teamwork and personal well-being. Outside of the workshop, team members network between classes they share with one another. As well, the team is no stranger to celebrating a hard-working day by going out together to catch a movie, grab refreshments, or even just hang out.
### Career Opportunities
UCalgary Baja provides you the opportunity to network with industry professionals from numerous industries, most notably in the automotive sector with the likes of Honda, Ford Motor Company, Volvo, Cummins, and many more. Alumni from the team have established engineering careers at such companies as these.
## Code of Conduct
Based on the 2018 Baja Charter
Although this does not apply, for the most part, to the Software Subteam, these are all important, including the safety aspects.
Safety should allow for any leave of absence or refusal of work.
UCalgary Baja reserves the right to remove any team member from the team if they are not compliant with the Code of Conduct. All issues will be dealt with on a case-by-case basis. We are investing in you and are here to work with you to make you and UCalgary Baja successful.
<ol>
<li>Safety is a core value. We care about keeping you safe! Continual negligence and disregard for safety will result in removal from the team. Safety is regarding:
<ul>
<li>Shop Safety
<ul>
        <li>Safety glasses are mandatory in the garage and hot works space</li>
<li>Close-toed shoes, long cotton pants and cotton long sleeves/shop smocks must be worn in the hot works area</li>
<li>Additional signage will be adhered to</li>
<li>A positive attitude is expected when reminded of the shop rules.
</ul>
    <li>Tool Safety - Abide by Team Policies and the SOP. Team Policies often have further precautions than the SOPs</li>
    <li>Housekeeping - All members are expected to assist in keeping workspaces tidy and egress paths clear.</li>
    <li>Driving - The rules of the road will be followed (i.e. speed limits shall not be exceeded when driving on behalf of UCalgary Baja, including rentals)</li>
    <li>Alcohol and Drug Use
<ul>
<li>No member shall enter the garage or hot works space under the influence of drugs or alcohol</li>
        <li>A 0.00 BAC is expected when handling tools or operating the vehicle</li>
</ul>
</li>
</ul>
<li> Commitment and Involvement
<ul>
<li>Treated the same as involvement in 1 to 2 engineering courses per semester</li>
<li>Members are responsible for managing their time to ensure coursework and UCalgary Baja work are both completed</li>
<li>You acknowledge that you are committed to this team and you understand that sacrifices will need to be made to to be a fully contributing member. Remember, You get out what you put in!</li>
<li>It is expected that you will give assigned projects your best effort</li>
<li>You will meet project deliverable deadlines</li>
<li>You will be called upon by the team if and when you are needed regarding your project and others’ projects</li>
<li>You will help your teammates achieve their goals</li>
</ul>
</li>
<li>Conduct
    <ul>
<li>You will exercise due diligence in all of your dealings on the team, be it in ensuring your designs, performing shop work, and respecting external relations with sponsors, vendors, and university administration.</li>
    <li>You are an ambassador for the UCalgary Baja, the Schulich School of Engineering and the University of Calgary and will act accordingly</li>
</ul>
</li>
<li>Attendance
<ul>
<li>Used to determine eligibility for competition.</li>
<li>You will inform your Team Lead if you are unable to attend and a reason why. Team Leads are responsible for informing the Team Captain on who is unable to make meetings</li>
<li>Consistent lack of attendance may result in removal from the team</li>
<li>Leave of Absence is always excused when safety is involved this will not count against your eligibility
<ul>
<li>Abuse of this policy will be considered and will count against your eligibility for competition.</li>
</ul>
</li>
<li>All attendance issues will be dealt with on a case-by-case basis</li>
</li>
</ol>
These rules can be superseded by the university rules or the club code of conduct.
These rules can also be superseded by governing bodies such as the government of any jurisdiction that work that software is applicable or is conducted in
Other bodies that could possibly have a say are IEEE (I triple E), the worker's Board of Alberta, Health and Safety Boards, etc.
## How do I report
If you wish to report a violation of any of these rules please talk to any of the lead(s) that you feel most comfortable with or the Captain.
This will be investigated promptly and action will be taken depending on the severity.
## Consequences / Infractions
1. Continuing underperformance and/or not meeting deliverables or commitments will lower your standing/ranking in attending competition
2. If there is still continued underperformance, UCalgary Baja may enact removal from the team
It is important to note that issues and concerns in performance addressed by UCalgary Baja will be dealt with on a case-by-case basis for every member. UCalgary Baja understands that there are circumstances in life that are beyond anyone’s control and will work with you to best solve these issues. If issues continue to persist and impact your ability to fulfill your commitment to UCalgary Baja, approach us to have a discussion and we can have you reevaluate roles and responsibilities on the team.
### DEI Software Specific Mandates
We do not have a mandate, the only mandate is trying to fill a full hotel room if gender matters/applicable.
ex. Fill a women's hotel room, ***PLEASE AVOID*** this situation, the worst is a half or quarter, please aim for as many full rooms if possible.
 
## Coding Coduct
This section outlines how programming and coding in all languages should generally be followed.
1. Readable code is valued above all else ie. Variable names that make sense, clear function names
1. Comment code even if it is obnoxious make it so that you or anyone besides yourself in 10 years can read what is going on.   Programs like ChatGPT are allowed to comment code automatically just as long as they make sense to you six months down the road
1. Use the Prettier extension as the default code formatter so that the code is consistent
1. Use git and use a new branch to create a new feature (be careful of the base of the branch)
1. Use pull requests to the dev branch to merge code
       
```
DO NOT MERGE TO THE PRODUCTION BRANCH (main or master normally)
```
1. Examples of base templates in most common languages are available below
1. Try to make code as modular and reusable as possible
1. Use ChatGPT but be warned you will spend more time on debugging than coding and ***most importantly YOU WONT LEARN***, USE IT FOR REGEX
1. Please include a permanent email and name if you write any code, this is just for questions on what x does (not mandatory)
    - If you write unreadable code you get emails in the future about it
    - Remove emails if completely refactored (75% of the code has been changed in some way)
```
DO NOT USE THIS TO GET ALUMNI TO DO YOUR WORK
```
# Operation of the Team
##  Organization Structure
## Team Structure and Reporting Hierarchy
This document outlines the reporting structure within the Software Subteam. Each role has specific responsibilities and reports to different levels of the team.
### Captain of Baja
- Can overrule task approval
- Can suggest projects
#### Software Lead
- **Reports to:** Captain of Baja
- **Chosen by:** Software Subteam and approved by Captain or voluntold by Captain
- **Min Requirements:** Not a Junior in the same year
- **Roles:** Mentor, code reviewer, task giver, project scheduler, designer, project/design approver, sysadmin of cloud/NAS
- **Language Access:** Python, HTML, CSS, JavaScript, YAML, JSON, XML, Lua, Rust, C, C++/Arduino, Java (please avoid), Golang, Terraform, Bash, Docker, Kubernetes, GitHub Actions
- **Summary:** They run the Software Subteam, have lots of projects complete, ensure that the cloud runs smoothly, enforce good coding practices, give out tasks/projects to senior members and approve.
##### Future Software Lead
- **Reports to:** Software Lead
- **Min Requirements:** 2 years with the club
- **Roles:** Mentors, can be sysadmin of cloud/NAS, code reviewer, designer, task giver
- **Language Access:** Python, HTML, CSS, JavaScript, YAML, JSON, XML, Lua, Rust, C, C++/Arduino, Java (please avoid), Golang, Terraform, Bash, Docker, Kubernetes, GitHub Actions
- **Summary:** Experienced member, teaches others, enforces coding practices, and designs/feedback on projects, should run atleast one project with the support of the software lead, this is in order to get them comfortable with the role.
##### Senior Member
- **Reports to:** Software Lead and Future Software Lead
- **Min Requirements:** 2 years with the club
- **Roles:** Mentors, can be sysadmin of cloud/NAS, code reviewer, designer, task giver
- **Language Access:** Python, HTML, CSS, JavaScript, YAML, JSON, XML, Lua, Rust, C, C++/Arduino, Java (please avoid), Golang, Terraform, Bash, Docker, Kubernetes, GitHub Actions
- **Summary:** They have a lot of projects complete, they are here to teach, give out tasks, enforce good coding practices and design how a project should be made with their designs and feedback.
###### Intermediate Member
- **Reports to:** Senior Member
- **Min Requirements:** 1-1.9 years with the club
- **Roles:** Mentor (possibly), Mentee (probably), code reviewer (possibly), design input (probably), designer (possibly)
- **Language Access:** Python, HTML, CSS, JavaScript, YAML, JSON, XML, Lua, Rust, C, C++/Arduino, Java (please avoid), Golang, Bash (basic commands and git), Docker, Kubernetes
- **Summary:** They have a few project(s) completed, they are still mostly here to learn, they can give better feedback on designs than juniors (starting to understand)
##### Junior Member
- **Reports to:** Software Lead and Senior Member
- **Min Requirements:** New to the club this year
- **Roles:** Mentee (Need, dependent on year), design input
- **Language Access:** Python, HTML, CSS, JavaScript, JSON, XML, JSON, Lua, Golang, Bash (basic commands and git)
- **Summary:** They are new and here to learn, they can give limited amounts of feedback about designs (due to a lack of knowledge)
This structure aims to provide a guide to members of software.
This does not mean that it is rigid it is a general guide to how the team members should operate and the level of expectations on them.
***Lanaguage Access***
This does not mean that anyone on any level of the hierarchy is not able to code in those languages **Willingly** it is meant to be interpreted as a guard for those who are lower in the chain from going into more difficult languages such as C or rust where the understanding is not able to be taught by the university in their first or second years.
***Roles***
This gives the expectation of the person the newer one is to the club the less they are expected to know and do for the software subteam.
***Reports to***
This is the group who is in charge of you the lead is not able to handle 8 people all on their own they need help, your mentor is there to help the Lead and future Lead and filter out a lot of the questions and task giving.
**The Captain most likely cannot help with software please go to the Software Lead as a last resort**
***Pair Programming***
This is a technique in programming where a mentor and mentee are paired up the mentee is expected to write the code and the mentor is expected to drive/tell the mentee what to write.
This is in hopes of giving the mentee exposure to the language and general programming concepts so that they may level up their skills.
## Roles and Expectations
based upon the 2018 Baja Charter
### All Members
- Your position on this team is a privilege, not a right.
- All members will follow through with commitments in a timely matter or inform your Team Lead/Team Captain if you cannot.
- Will be present and attend meetings/workdays on time at the times specified.
- Unless Exceptions are given either by the Software Lead or Team Captain
- This includes an Internship program where Wednesdays are optional
- Exams always
- Safety always
- Software Lead is on Internship, Wednesdays will either be optional or lead by a Senior member or Future Software Lead
- Team members will need to be a part of all phases of your assigned project and possibly projects that you aren't part of - Design, & Coding. This ensures that mistakes, issues, and concerns are addressed ASAP and corrected accordingly.
- Asking questions is encouraged and is the greatest way for you to learn. Every member will be open to taking questions. If you are unable to answer a question either admit that “I don’t know”, or suggest someone who may be better qualified to answer the question. Asking questions is beneficial for both parties as it expands the asker’s knowledge base, and keeps the question recipient current with their knowledge
- Googling the docs or Stackoverflow is a great start
### Juniors
- Are expected to work and ask questions. Enthusiasm to learn and a positive attitude is a must!
### Intermediates
- In addition to Junoir Member roles and expectations:
- Expected to carry out some of their own research and ask whatever questions they may have about their project. They may not necessarily know everything about the language/project but must make an effort to verse themselves as completely as they can.
- Can Volunteer to teach Juniors and other members new skills and assist in the transfer of knowledge.
- A Developmental level amount of time management to ensure adequate research and development of your design projects is a must.
### Seniors
- In addition to Intermediate Member roles and expectations:
- Expected to carry out their own research and ask whatever questions they may have about their project. They may not necessarily know everything about the language/project but must make an effort to verse themselves as completely as they can.
- Are expected to be able to take on more challenging design projects on the vehicle.
- Effective time management to ensure adequate research and development of your design projects is a must.
- During each season, must be willing to teach Juniors and other members new skills and assist in a transfer of knowledge.
- Can request a member be reassigned to another group
- Must check in regularly with everyone in their group to ensure they are learning and making progress on a weekly or bi-weekly basis.
- Reports will also be conducted by the team lead
### Team Leads
- In addition to Senior Member roles and expectations:
- Are responsible for all members, projects, components, and hardware within their system. If progress is not being made, it is their responsibility to work with the designer/programmer to ensure timelines are met.
- May assign and reassign projects as they see fit.
- Must empower, guide, and facilitate their members learning and projects.
- Must check in regularly with everyone on their system team to ensure they are learning and making progress on a weekly or bi-weekly basis.
- Enforce with encouragement what teammates are learning and provide insight on their designs.
- Will work alongside their future lead. This does not mean offloading your workload to the future lead as a means to shy away from Baja's responsibilities and commitments.
- Expected to be the final decision maker regarding any project within their system.
- The Software lead will be in consistent contact with Senior members to ensure that a project is running smoothly.
- Team leads will be in consistent contact with one another (primarily Electrical and Business) to ensure designs housed/shared by systems are working in tandem.
### Future Team Leads
- In addition to Senior Member roles and expectations:
- Work alongside their team lead to learn how to manage the system team
- Act to the best of their ability to aid and advise the system team lead concerning current and future work and tasks to be done
- Act to the best of their ability to provide design insight to fellow system teammates under the direction of his or her system lead
## Seasons
There are multiple phases throughout the year. As UCalgary Baja is a competition team focused on performing well all members are expected to have full involvement in each phase. The Baja year can be broken down into the following cycle (It is important to note that each phase may feather into one another):
Timelines in Software are flexible this is a guide to the year not a set in stone, some project scopes may take longer than others.
### 2025 Season Edit **Mech/Electrical**
This year the school has reduced the nubmer of shop tech hours and removed many alot of the shop time in favor of a class, this mean that everyone is under crunch and we only get a limited amount of time, limited number of people we can train to work in the machine and one designated cnc machine that must be used or we lose it
### Summer - Testing **Mech/Electrical**
This is when UCalgary Baja tests the previous vehicle to influence designs for the future vehicle. Testing consists of gathering data from the previous vehicle to influence design decisions for the new vehicle. Such tests may include strain gauge impact testing, vehicle roll testing, transmission dynamometer characterization, etc.
#### Summer Semster 2025 Season Edit **Mech/Electrical**
The new car designs start here, we need something for Fall to be made. This does not mean summer testing cant happen at the same time but rather creating something for the Fall manufacting timeslot is more important.
### Summer - Testing **Software**
The software could get involved in this time, this time should primarily be used for the setup/preparation for the new season, recruitment period, and any SSAF requests and allowing for the new lead to get situated and plan the projects for the year, this time also allows the old lead to mentor as well as they can the new lead.
This is a time where a break can be taken such as only meeting every second week.
### Fall Semster 2025 Season Edit **Whole Team**
A number of deliverables get done
1. SSAF funding for the main manufacturing period (Winter Semster)
1. Recuitment
### Fall Semester - Design **Mech/Electrical**
The design period involves brainstorming, drafts, CAD modelling, design reviews, system collaboration, document creation, drawing submission, hardware sourcing, material sourcing and manufacture sourcing for all projects.
#### Fall Semster 2025 Season Edit **Mech/Electrical**
For fall this means that as much manufacting as possible happens here, any finished designs are manufactured by the new (and forced upon) manufacting group/team, this happens at the same time as designs are being made/CADed.
New members of the manufacting group are trained during this time, the number of new people is determined by the university/machine shop and then is selected based upon commitment and free time during the week (sorry we this sometimes happens to be the only times available for us to get into the shop)
### Fall Semester - Easier Projects **Software**
This is the time when either your first or the easier projects happen, typically the projects involve higher-level languages like Python, JavaScript, HTML, CSS or high-level programming where the background level is low, it should be typically reserved for learning opportunities even if the club needs the tool.
This is a time for learning and enforcing good programming rules.
Recruitment also happens during this time which reduces the amount of time able to be spent on complex projects.
### Winter Semester - Fabrication **Mech/Electrical**
Time to get your hands dirty! Fabrication is when the car is built and parts are submitted to machine shops. Learn to use tools and understand the importance of designing for manufacturability. This period provides the opportunity to learn the most about the vehicle, how its projects and systems work together, and assemble a vehicle!
#### Winter Semster 2025 Season Edit **Mech/Electrical**
Not much changes here other than the manufacting team is in full swing, anything else that is made outside of the machine shop goes on as normal.
### Winter Semester - Harder Projects **Software**
The concepts learned from the fall semester are now built upon in more difficult tasks such as testing (boundary, inner whatever the lead decides is appropriate to accomplish)
This time can also be spent wrapping up easier projects, possibly continuing on with projects that were originally thought to be easy but instead turned out to be difficult
### Late Winter to Early Spring - Pre-Competition Testing **Mech/Electrical**
In this phase, tests will be performed to validate the new vehicle’s designs. Examples of tests performed are torsion tests, locating center-of-gravity, impact testing, transmission dynamometer, etc.
#### Late Winter to Early Spring 2025 Season Edit **Mech/Electrical**
Normally this is our crunch time, please expect to spend up to 13 hours a day on Baja. This does not mean school comes second, this is just meant to inform you
### Late Winter to Early Spring **Software**
No changes from the start of the Winter Semester
The addition of the Online Cost Report is the responsibility of the lead and senior members collaborating with electrical members.
Rules for software as of the 2025 season
If any data collection system is on the car it must be included then a software component of the Online cost report must be completed.
**The SSAF travel fund is a priority and any work can be stopped to help finish it**
**We do not go to comp if no SSAF travel fund is completed**
### Just Before Competition - Vehicle Tuning & Driver Training **Mech/Electrical**
Vehicle tuning consists of testing and recording multiple setups of the drivetrain, suspension, and braking systems. This allows the team to find the best settings for each event the vehicle will come up against. Alongside tuning, drivers who prove themselves as confident, comfortable, and skilled in the driver’s seat will be chosen to drive specific events at the competition. Efforts will be taken to emulate events and train drivers accordingly.
### Just Before Competition 2025 Season Edit **Whole Team**
A SSAF funding round happeens so that we get buy things for the Fall Semster manufacturing period
### Just Before Competition **Software**
If reasonable Software transforms into the tool fetchers if work is behind
Other tasks include cleaning the truck (with a shop vac) cleaning the trailer (sweeping dirt out) and removing any garbage from the truck and trailer.
The reason why is that your fellow members are going to spend 10+ hours living there, so make sure it is comfortable for them and so that they do not have to clean it before driving to the competition
Reasonable is no juniors or other members available to perform this task.
The highest priority is to get the car out the door.
### May to June - Competition
The moment we’ve all been waiting for! Competition is where all your blood, sweat, and tears invested in the vehicle pay off. It is the ultimate testament to what the vehicle was designed to do. The competition consists of static events (business and design presentations), dynamic events (acceleration, maneuverability, hill climb, suspension & traction, and rock crawl), and finally a 4-hour endurance race.
### May to June - Competition **Software**
We help where we can, that could be running the sim for the driver, fetching tools (hence why the previous phase), taking photos, helping businesses, helping where you can
### Repeat
Summer is the transition phase, and Fall is the start of a new season
Prepare for the next phase as well as you can
# How To's
This can be found also in Baja Data Current Year/W - Software/Software Standardizations and Common Git Commands.md.
The most up-to-date is in the current year.
## Baja UofC Software Standards
### Git
The stupid content tracker.
No more need for V1, V2, V2 Final or V2 Final Final edit by Malik Final
This terminal-based program is a lightweight version control, that is highly useful for dealing with code/text activities.
This does not require a remote origin, a local repo will be fine with the use of the Baja Cloud, just upload any .git files with it.
This will track everything in the specified git directory (files, child directories, etc.)
#### Common Commands
###### Note
Need to be in a git repo directory to use git commands.
```bash
# change directory
cd <name/path>
# Go to the parent directory
cd.
# initialize a git repository (local only)
git init
# add (stage) all changes (in files)
git add -A
# Commit staged changes with a message
git commit -m "commit message"
# create a new branch and check into it
git checkout -b <branch-name>
# change the current branch to an existing branch
git checkout <branch-name>
# delete a branch
git branch -D <branch-name>
# set upstream (default remote branch) for a local branch
# (upload)
git push -u origin <branch-name>
# pull the latest changes from the remote repository
# (download)
git pull origin <branch-name>
# revert a commit
git revert <commit-hash>
# see commit logs (multi-line includes the date, who and other useless info)
# Is much longer
git log
# see logs in one line (with commit hash)
# shorter
git log --oneline
# see the list of both local and remote branches
git branch -a
# see the list of local branches
git branch
# see the status of the current local repository
# see what files/changes are uncommitted
git status
# rebase a branch with another one
git rebase <branch-name>
# see remote repositories linked to the current local repository
git remote -v
# add a new origin (remote repository)
git remote add origin <origin-url>
# cache GitHub credentials
git config --global credential.helper 'cache --timeout=36000'
# remove git cache
git rm -r --cached.
# config username and email for a git project
git config user.name "username"
git config user.email "email"
```
<h2>Git cheat sheet</h2>
<p>The commands discussed above–and more–are summarized in this cheat sheet available to <a href="https://wac-cdn.atlassian.com/dam/jcr:e7e22f25-bba2-4ef1-a197-53f46b6df4a5/SWTM-2088_Atlassian-Git-Cheatsheet.pdf?cdnVersion=691">download</a>.</p>
#### Type
Must be one of the following:
- **init**: A special case only for the very first commit (example: init(location))
- **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
- **ci**: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
- **docs**: Documentation only changes
- **feat**: A new feature
- **fix**: A bug fix
- **perf**: A code change that improves performance
- **refactor**: A code change that neither fixes a bug nor adds a feature
- **style**: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc)
- **test**: Adding missing tests or correcting existing tests
- **chore**:
- **added**: Added content but not a complete feature
- **removed**: Removed files or content only
- **merged**: Used when a branch's content is merged into another branch
#### Message
The subject contains a succinct description of the change (this will show up in the logs):
- use the imperative, present tense: "change" not "changed" nor "changes"
- don't capitalize the first letter
- no dot (.) at the end
#### Example Commit
```bash
git add -A # adds all of the files/changed files to the commit stage (pre-commit)
```
```bash
git commit -m"feat(DAQ)^: optimized algorithm" # the message that will show up in the logs
```
Another Example
```bash
git commit -m"Feat (API)^: send an email to the customer when a product is shipped"
```
#### How to Commit
```
"<type>(scope or file that has been changed): short description"
```
Replace <type> with just the type
^ for any breaking commits
#### Why?
How long do you think this code will be used? 1 year? 1 decade? 4 weeks?
You don't know so make life easier on yourself and new juniors comment on what your code does, it doesn't have to be line by line but at least explain a "block" or a related section of code to the purpose/what it does.
### Example Comments and Function Starters
Based off JSDoc standard can be found [here](https://jsdoc.app)
#### JavaScript
Uses [JSDoc](https://jsdoc.app) standard
```js
//More preferred arrow function just needs to call function and does function immediately
/**
* @param {Object} inputVar - one argument into the function should be its name
* @param {number} b - one argument into the function should be its name
* @returns {Promise<number>} c - what the program returns with type
* @description A brief description of what the function does
* @author Name <semiperminant@exmaplemail.com>
// semi-permanent email, do not need to respond but try to be a good alumni
*/
const exampleFunct = (inputVar) => {
// comments annotate the line below them
// constant variable cannot change, not strongly typed
const varExample0 = 0;
// local variable, not strongly typed can be any data type
let varExample1 = 0;
// global variable, not strongly typed can be any data type
var varExample2 = 0;
// example function does nothing significant
  return 0;
};
/**
* @param {Object} inputVar - one argument into the function should be its name
* @param {number} b - one argument into the function should be its name
* @returns {Promise<number>} c - what the program returns with type
* @description A brief description of what the function does
* @author Name <semiperminant@exmaplemail.com>
// semi-permanent email, do not need to respond but try to be a good alumni
*/
function exampleFunct2(inputVar) {
// comments annotate the line below them
// constant variable cannot change, not strongly typed
const varExample0 = 0;
// local variable, not strongly typed can be any data type
let varExample1 = 0;
// global variable, not strongly typed can be any data type
var varExample2 = 0;
// example function does nothing significant
return 0;
};
```
#### Python
```python
# comments normally annotate the line below, python functions/classes/methods are the only expection
def example_funct(input_var:type):
"""
What function does
`PARAMS`:
- Name_of_var `type` - Addtional details of what is required
`RETURNS`:
- Name_of_var `type` - Additional details of what is required
`AUTHOR(S)`:
- Your Name
`Contact`:
- semi-permanent email, do not need to respond but try to be a good alumni
- Example of two items
"""
# example variable can be anything not just an int
var_example = 0
# example function does nothing significant
return 0
```
#### Rust
```rust
fn exampleFunc () {
// I have not decided yet
}
```
#### C++
```cpp
/*
What function does
PARAMS:
- nameOfVar `type` - Addtional Detals (if applicable)
PROMISES:
- nameOfVar `type` - Additional Details (if applicable)
AUTHOR(S):
- Your Name
CONTACT:
- semi-permanent email, do not need to respond but try to be a good alumni
- Example of two items
*/
int exampleFunct (int inputVar) {
// comments annotate the line below them
int varExamlpe;
// example variable, is strongly typed. Can only be an integer
int varExample1 = 0;
// example function does nothing significant.
return 0;
};
```
#### C
```c
/*
What function does
PARAMS:
- nameOfVar `type` - Addtional Detals (if applicable)
PROMISES:
- nameOfVar `type` - Additional Details (if applicable)
AUTHOR(S):
- Your Name
CONTACT:
- semi-permanent email, do not need to respond but try to be a good alumni
- Example of two items
*/
int exampleFunct (int inputVar) {
// comments annotate the line below them
int varExample0;
// exampe variable is strongly typed. In this case can only be an integer
int varExample1 = 0;
// example function does nothing significant
return 0;
};
```
#### Java/C#
```java
// these languages is cursed and full of boilerplate
// use anything else if you can
// high memory overhead, use C++ instead
// you can add standard here just make it similar to the rest
```
#### Golang
```golang
// I dont know
// you can add standard here just make it similar to the rest
```
#### Lua
```lua
-- I dont know
-- you can add standard here just make it similar to the rest
```
#### Terraform
This will probably only used for cloud applications
```terraform
<!--
I dont know
you can add standard here just make it similar to the rest
-->
```
#### HTML
This is the same as any other page, not unique, should still vet in a html validator/best practices
author goes in human.txt, for more info please see [here](https://humanstxt.org)
```html
<!doctype html>
<html>
<head>
<title>Our Funky HTML Page</title>
<meta name="description" content="Our first page">
<meta name="keywords" content="html tutorial template">
</head>
<body>
Content goes here.
</body>
</html>
```
#### JSON, YAML, XML, CSS
These are more like data types/file format, follow rules of the language
#### Bash
Always starts with a shebang
```bash
#!
echo "Hello World!"
# I dont know
# you can add standard here just make it similar to the rest
```
#### Github Actions
Please find example in any baja repo under .github/workflows/*.yaml
star is a wildcard and in this case represents any name of the file

383
Software Standardizations and Common Git Commands.MD Normal file
View File

@ -0,0 +1,383 @@
This section outlines how programming and coding in all languages should generally be followed.
1. Readable code is valued above all else ie. Variable names that make sense, clear function names
1. Comment code even if it is obnoxious make it so that you or anyone besides yourself in 10 years can read what is going on.   Programs like ChatGPT are allowed to comment code automatically just as long as they make sense to you six months down the road
1. Use the Prettier extension as the default code formatter so that the code is consistent
1. Use git and use a new branch to create a new feature (be careful of the base of the branch)
1. Use pull requests to the dev branch to merge code
       
```
DO NOT MERGE TO THE PRODUCTION BRANCH (main or master normally)
```
1. Examples of base templates in most common languages are available below
1. Try to make code as modular and reusable as possible
1. Use ChatGPT but be warned you will spend more time on debugging than coding and ***most importantly YOU WONT LEARN***, USE IT FOR REGEX
1. Please include a permanent email and name if you write any code, this is just for questions on what x does (not mandatory)
    - If you write unreadable code you get emails in the future about it
    - Remove emails if completely refactored (75% of the code has been changed in some way)
```
DO NOT USE THIS TO GET ALUMNI TO DO YOUR WORK
```
# Git
The stupid content tracker.
No more need for V1, V2, V2 Final or V2 Final Final edit by Malik Final
This terminal-based program is a lightweight version control, that is highly useful for dealing with code/text activities.
This does not require a remote origin, a local repo will be fine with the use of the Baja Cloud, just upload any .git files with it.
This will track everything in the specified git directory (files, child directories, etc.)
## Common Commands
### Note
Need to be in a git repo directory to use git commands.
```bash
# change directory
cd <name/path>
# Go to the parent directory
cd.
# initialize a git repository (local only)
git init
# add (stage) all changes (in files)
git add -A
# Commit staged changes with a message
git commit -m "commit message"
# create a new branch and check into it
git checkout -b <branch-name>
# change the current branch to an existing branch
git checkout <branch-name>
# delete a branch
git branch -D <branch-name>
# set upstream (default remote branch) for a local branch
# (upload)
git push -u origin <branch-name>
# pull the latest changes from the remote repository
# (download)
git pull origin <branch-name>
# revert a commit
git revert <commit-hash>
# see commit logs (multi-line includes the date, who and other useless info)
# Is much longer
git log
# see logs in one line (with commit hash)
# shorter
git log --oneline
# see the list of both local and remote branches
git branch -a
# see the list of local branches
git branch
# see the status of the current local repository
# see what files/changes are uncommitted
git status
# rebase a branch with another one
git rebase <branch-name>
# see remote repositories linked to the current local repository
git remote -v
# add a new origin (remote repository)
git remote add origin <origin-url>
# cache GitHub credentials
git config --global credential.helper 'cache --timeout=36000'
# remove git cache
git rm -r --cached.
# config username and email for a git project
git config user.name "username"
git config user.email "email"
```
<h2>Git cheat sheet</h2>
<p>The commands discussed above–and more–are summarized in this cheat sheet available to <a href="https://wac-cdn.atlassian.com/dam/jcr:e7e22f25-bba2-4ef1-a197-53f46b6df4a5/SWTM-2088_Atlassian-Git-Cheatsheet.pdf?cdnVersion=691">download</a>.</p>
## Type
Must be one of the following:
- **init**: A special case only for the very first commit (example: init(location))
- **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
- **ci**: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
- **docs**: Documentation only changes
- **feat**: A new feature
- **fix**: A bug fix
- **perf**: A code change that improves performance
- **refactor**: A code change that neither fixes a bug nor adds a feature
- **style**: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc)
- **test**: Adding missing tests or correcting existing tests
- **chore**:
- **added**: Added content but not a complete feature
- **removed**: Removed files or content only
- **merged**: Used when a branch's content is merged into another branch
## Message
The subject contains a succinct description of the change (this will show up in the logs):
- use the imperative, present tense: "change" not "changed" nor "changes"
- don't capitalize the first letter
- no dot (.) at the end
## How to Commit
```
"<type>(scope or file that has been changed): short description"
```
Replace <type> with just the type
^ for any breaking commits
## Example
```bash
git add -A # adds all of the files/changed files to the commit stage (pre-commit)
```
```bash
git commit -m"feat(DAQ)^: optimized algorithm" # the message that will show up in the logs
```
Another Example
```bash
git commit -m"Feat (API)^: send an email to the customer when a product is shipped"
```
## Why?
How long do you think this code will be used? 1 year? 1 decade? 4 weeks?
You don't know so make life easier on yourself and new juniors comment on what your code does, it doesn't have to be line by line but at least explain a "block" or a related section of code to the purpose/what it does.
# Example Comments and Function Starters
Based off JSDoc standard
## JavaScript
Uses [JSDoc](https://jsdoc.app) standard
```js
//More preferred arrow function just needs to call function and does function immediately
/**
* @param {Object} inputVar - one argument into the function should be its name
* @param {number} b - one argument into the function should be its name
* @returns {Promise<number>} c - what the program returns with type
* @description A brief description of what the function does
* @author Name <semiperminant@exmaplemail.com>
// semi-permanent email, do not need to respond but try to be a good alumni
*/
const exampleFunct = (inputVar) => {
// comments annotate the line below them
// constant variable cannot change, not strongly typed
const varExample0 = 0;
// local variable, not strongly typed can be any data type
let varExample1 = 0;
// global variable, not strongly typed can be any data type
var varExample2 = 0;
// example function does nothing significant
  return 0;
};
/**
* @param {Object} inputVar - one argument into the function should be its name
* @param {number} b - one argument into the function should be its name
* @returns {Promise<number>} c - what the program returns with type
* @description A brief description of what the function does
* @author Name <semiperminant@exmaplemail.com>
// semi-permanent email, do not need to respond but try to be a good alumni
*/
function exampleFunct2(inputVar) {
// comments annotate the line below them
// constant variable cannot change, not strongly typed
const varExample0 = 0;
// local variable, not strongly typed can be any data type
let varExample1 = 0;
// global variable, not strongly typed can be any data type
var varExample2 = 0;
// example function does nothing significant
return 0;
};
```
## Python
```python
# comments normally annotate the line below, python functions/classes/methods are the only expection
def example_funct(input_var:type):
"""
What function does
`PARAMS`:
- Name_of_var `type` - Addtional details of what is required
`RETURNS`:
- Name_of_var `type` - Additional details of what is required
`AUTHOR(S)`:
- Your Name
`Contact`:
- semi-permanent email, do not need to respond but try to be a good alumni
- Example of two items
"""
# example variable can be anything not just an int
var_example = 0
# example function does nothing significant
return 0
```
## Rust
```rust
fn exampleFunc () {
//I have not decided yet
}
```
## C++
```cpp
/*
What function does
PARAMS:
- nameOfVar `type` - Addtional Detals (if applicable)
PROMISES:
- nameOfVar `type` - Additional Details (if applicable)
AUTHOR(S):
- Your Name
CONTACT:
- semi-permanent email, do not need to respond but try to be a good alumni
- Example of two items
*/
int exampleFunct (int inputVar) {
// comments annotate the line below them
int varExamlpe;
// example variable, is strongly typed. Can only be an integer
int varExample1 = 0;
// example function does nothing significant.
return 0;
};
```
## C
```c
/*
What function does
PARAMS:
- nameOfVar `type` - Addtional Detals (if applicable)
PROMISES:
- nameOfVar `type` - Additional Details (if applicable)
AUTHOR(S):
- Your Name
CONTACT:
- semi-permanent email, do not need to respond but try to be a good alumni
- Example of two items
*/
int exampleFunct (int inputVar) {
// comments annotate the line below them
int varExample0;
// exampe variable is strongly typed. In this case can only be an integer
int varExample1 = 0;
// example function does nothing significant
return 0;
};
```
## Java/C#
```java
// these languages is cursed and full of boilerplate
// use anything else if you can
// high memory overhead, use C++ instead
// you can add standard here just make it similar to the rest
```
## Golang
```golang
// I dont know
// you can add standard here just make it similar to the rest
```
## Lua
```lua
-- I dont know
-- you can add standard here just make it similar to the rest
```
## Terraform
This will probably only used for cloud applications
```terraform
<!--
I dont know
you can add standard here just make it similar to the rest
-->
```
## HTML
This is the same as any other page, not unique, should still vet in a html validator/best practices
author goes in human.txt, for more info please see [here](https://humanstxt.org)
```html
<!doctype html>
<html>
<head>
<title>Our Funky HTML Page</title>
<meta name="description" content="Our first page">
<meta name="keywords" content="html tutorial template">
</head>
<body>
Content goes here.
</body>
</html>
```
## JSON, YAML, XML, CSS
These are more like data types/file format, follow rules of the language
## Bash
Always starts with a shebang
```bash
#!
echo "Hello World!"
# I dont know
# you can add standard here just make it similar to the rest
```
## Github Actions
Please find example in any baja repo under .github/workflows/*.yaml
star is a wildcard and in this case represents any name of the file