Onboarding

Guide and best practices for Blueprint Developers on both Project Teams and Tech Team. We recommend reading this if you are new to any Blueprint role: E-Board Member, Technical Lead, Product Manager, Designer, and Developers!

Onboarding for Tech Team

Onboarding

How does the Tech Team work?


Git/Github

Making Your First Contribution!

This will be instructions on how to make your first contribution, with the example of adding John Doe to the list of contributors.

  1. Cloning the repository.
    • Open a new terminal and type the git clone command followed by the GitHub repository you want to clone. In this case, it would be git clone https://github.com/stevensblueprint/blueprint_website.git. This should create a new folder on your computer with the name of the repository.
    • Cloning the repository creates a local copy of all the code that you can edit on your computer. This only needs to be run once and from here, you can keep editing this local copy and updating it from the GitHub repository when needed.git_clone_command.png
  2. Creating a new branch.
    •  Open the folder of the local repository and run the git checkout command followed by the name of the branch. When naming a branch, it's good to pick a short, descriptive name. In our case, we are adding a contributor, so we'll type git checkout -b contributors/johnDoe.
    • Notice the -b? That's used to create a new branch as opposed to checking out a branch that already exists.
    • Creating a new branch makes a new version of the code that is isolated from the main code. This means changes can be made without affecting the main code (in case something goes terribly, disastrously wrong).creating_new_branch1.png
  3. Making the change!
    • Open the file you want to edit and make the necessary changes. In this case, we will be adding John Doe to the list of contributors.making_first_change.png
    • Make sure to save the file!

  4. Adding a file to a commit.
    • Once the change is made, use the git add command followed by the local file path to the changed file, in order to include or 'stage' the change them for the next commit. Commits can be thought of as checkpoints; more on that later.
    • In this case, we made changes to the CONTRIBUTORS.MD file in the .github folder, so our file path is .github/CONTRIBUTORS.MD and we type in git add .github/CONTRIBUTORS.MD.
    • You can use git add multiple times to add as many files as you need.
    • Another option is to use git add . to add all files with changes.adding_changes_to_commit1.png
    • Note that the file path is case sensitive.

  5. Checking changes to be committed.
    • You can use the git status command to check what files have been added or "staged" for a commit. In this case, it's only the one contributors file that we added.git_status_command.png
    • You can see here that our file is under changes to be committed and is in green text. Changes not staged for commit will be in red.

  6. Committing changes.
    • With our changes made and staged, we can create a commit which is basically a checkpoint for our code. We can revert to this point if we make mistakes or need to look at the version of the code at this point in time.
    • It is also good practice to include a commit message by using the -m flag to describe what changes were made. For us, we will just say that we are adding a new contributor, like so: git commit -m "Added a new contributor!".
    • We can commit as often as we want, or when we feel it is necessary before making big changes.git_commit_command.png
  7. Pushing the commit.
    • In order for our changes to appear on the remote repository (the one on Github), we need to push our changes using the git push command. If we run it as is, however, we will encounter an error:git_push_command_1.png
    • This is because when we create the branch contributors/johnDoe, we only created it locally and it does not exist on the Github repository. Therefore, we must run the command shown: git push --set-upstream origin contributors/johnDoe.git_push_command_2.png
    • Once the branch is set up remotely, or if the branch already existed remotely and was not created locally, we can simply use git push.
  8. Creating a pull request.
    • Once we have completed our task and pushed the changes, we can work on merging the changes back into the main code. To do this, we can create something called a pull request (PR for short) where we essentially propose the changes we made.
    • Going onto Github, you will likely see a pop-up asking if you want to create a pull request for your branch. If so, press "Compare & pull request".making_pull_request.png
    • If you don't see it, you can also create a new pull request by navigating to the "Pull requests" tab and selecting "New pull request".navigate_to_new_pr.png
  9. Approvals and Merging.
    • Next, you can put in details for your pull request such as a title and detailing what changes were made on your branch.new_pull_request.png
    • You will also see a list of approvals, some of which are run automatically. It is also necessary for at least one person to review your pull request before you can merge it with the main branch. Once your pull request is approved, hit "Squash and merge". You're done!merging_request.png
  10. What Now?
    • In order to keep your local copy updated with the remote repository (on GitHub), you can run the git pull command. This pulls all the changes made by other people.
    • For each task, your process should be something like this:
      • Step 2, create a new branch
      • Repeat Steps 3-7 as you work on your task and make changes
      • Steps 8-9 when you complete your task
        • Make revisions as needed.

Project Board and Tasks

Now that you know how to make changes, there's the questions of what to change.

Tasks
Project Board

If you're ever unsure of which task to pick up or having difficulty completing a task, drop by a Tech Team meeting and ask!

Git/Github Quick Reference

New to Git and Github? Checkout these resources:

Overview of Git and Github: https://wiki.sitblueprint.com/books/onboarding/page/contributing-to-blueprint-gitgithub

Full comprehensive guide/walkthrough of Git and Github: GitHub Foundations - Training | Microsoft Learn

If you prefer a comprehensive book: https://git-scm.com/book/en/v2

Or comprehensive video: Git Tutorial for Beginners: Learn Git in 1 Hour

Git Clone

git clone [<repository>]

Git Pull

git pull

Git Checkout

git checkout [-b] [<branch>]

Git Add

git add [<path>]

Git Commit

git commit [-m <message>]

git push

Contributing to Blueprint - git/GitHub

How to contribute?

All of our projects are hosted on GitHub. Being able to contribute to any GitHub is an essential skill for any developer; let's learn how to do it. If you would like a more in depth guide on contributing in GitHub, refer to the Tech Team Onboarding Guide

Click here to view the Stevens Blueprint GitHub.

What are git and GitHub? What are their differences?

Check out these resources for more detail on how to use the technologies:

Git and GitHub are essential tools in the world of software development, used for version control and collaboration. They serve related but distinct purposes, and understanding their main features and differences is key to utilizing them effectively.

Git

Git is a free, open-source version control system designed to handle everything from small to very large projects with speed and efficiency. It was created by Linus Torvalds in 2005 to support the development of the Linux kernel. Git operates on your local computer and allows you to keep track of changes to your files and code. Its main features include:

GitHub

GitHub is a web-based hosting service for version control using Git. It provides a cloud-based platform for developers to store, manage, and track changes to their code projects. GitHub was launched in 2008 and has become one of the most popular platforms for code hosting and collaboration. Its main features include:

Main Differences

Joining Blueprint's GitHub Organization

In order to join the Stevens Blueprint GitHub organization you must do the following:

  1. Install Git
  2. Create a GitHub Account (Instructions here)
  3. Send your GitHub username or email associated with your GitHub account to a member of the Stevens Executive Board. Once they said the invite it will appear in your email inbox and you must accept the invitation. 

Once you are part of the GitHub organization you can begin working on your respective project!

Product Management & Agile at Blueprint

This article explores how effective communication and streamlined meetings, leveraging platforms like Discord and GitHub (focusing on Issues and Project Boards) within Agile Project Methodology, can significantly enhance software development collaboration. Our goal is to provide strategies to optimize these tools, improving team efficiency and project outcomes.

Teamwork makes the dream work

Using Agile/Scrum in Blueprint Teams

Agile

Agile Methodology is a project management approach used primarily in software development. It focuses on delivering value through flexible, iterative progress rather than following a fixed plan. Agile emphasizes collaboration, customer feedback, and small, rapid releases of software.

Key Concepts:

Scrum

Scrum is a framework that implements Agile principles. It provides a structured, yet flexible way to manage projects.

Key Concepts:

This is a VERY brief and general introduction to Agile and Scrum. Please refer to the additional resources for more information.

How Blueprint Developers can Follow These Principles and Frameworks (Scrumprint)


Given the unique structure of Blueprint, adhering strictly to a traditional Scrum framework is not feasible for us. Our commitment to academic and extracurricular activities, alongside the absence of a standard 9-5 work schedule, necessitates a more flexible, hybrid approach to project management. Consequently, we are tasked with tailoring industry-standard methodologies to accommodate the diverse schedules of our student team members. Recognizing the dynamic nature of this adaptation, we remain open to continuous feedback and anticipate that our approach will evolve over time. The following outlines an adapted framework we encourage teams to implement

Roles

Events

Goals and Additions:

The next sections will show how tools like GitHub and Discord can be used to encourage this framework.

Joining & Interacting in Discord

Discord is our primary mode of communication used for project teams, tech teams, and general blueprint announcements. You can join Discord using this link: Blueprint Discord Link. Upon joining the server, you will be prompted to change your username to [FIRSTNAME] [LASTNAME] ['YEAR]. For example: "Atilla Duck '25". There are a lot of users on the Discord, so please do this as soon as possible. 

If you are on a Project Team or a Tech Team project we kindly ask that you leave the notifications on for your respective channel.

Make Use of Discord Features

There are several features that you can make use of in Discord to help organize channels.

Pinning Messages: Use this to save the most important messages in your channel for quick access. This can include Project Proposal Documents, Links to specific resources, or important channel guidelines that you want to save in the channel. 

Threads: Use threads to manage conversations on a specific topic. Perhaps their is a bug that someone needs help with or the Project Leader would like to collect team members opinions on a new feature. Using threads leaves the main channel less cluttered. Threads can be used for the Async Stand up events from the Scrumprint framework.

@People: Use the @ feature in your messages to get the attention of specific users or roles. Do not be afraid to make use of this feature if you need help with something or if someone has been unresponsive. "@here" is a good way to get the attention of everyone in a respective channel.

Reactions: It's respectful to acknowledge your teammates messages! Thankfully discord makes this easy so you can throw a quick thumbs up without having to type anything.

Webhooks

Webhooks make it easy way to get automated messages and data updates sent to a text channel in your server. Each project team and tech team project channel will be accompanied by another "-hooks" channel. This channel connects to the team's repository on GitHub. Whenever someone makes a contribution (commits code, opens a Pull Request (PR), comments on an issue, etc.) the "-hooks" channel will be notified. Currently, the Webhooks are configured to output the results of certain tests whenever you commit code. This makes it easy for you to see the activity going on in your project!

GitHub Project Boards & Issues

GitHub offers more than just hosting our repositories. There are two features that we can make use of to help organize tasks and adhere to the Scrumprint framework. 

Project Boards

Project Boards on GitHub offer a dynamic and intuitive interface for managing the various stages of our tasks. By creating Kanban boards, we can streamline our workflow into three fundamental columns, which simplifies the process of tracking progress throughout the development cycle. This method not only aids in maintaining organization but also ensures that our team remains aligned with the goals of each sprint. Here's how Project Boards can be utilized effectively:

image.png

Follow this guide to create a project.

Issues

GitHub Issues are a powerful tool within GitHub's ecosystem, designed to facilitate collaboration and communication on projects hosted on the platform. They serve as a primary method for tracking various tasks related to software development, including bug reports, feature requests, enhancements, and general questions or discussions. Here's a closer look at how GitHub Issues can be utilized:

image.png

Issues should be descriptive and it should be clear what the requirements and scope of the task are.

Additional Resources

Introduction to UI/UX Design

See the attached PDF for slides: GBM #2_ UI_UX Design Workshop.pdf

The UI/UX Design Workshop emphasized the importance of the design process in building user-friendly digital products. Here are some of the essential points covered, along with additional insights for aspiring UI/UX designers:

Understanding Your Role in a Design Project

As a UI/UX designer, your primary responsibility is to create intuitive, engaging designs while collaborating with tech leads, project managers, and developers. It’s essential to:

Identifying Bad UI/UX

We explored several examples of bad UI/UX and identified key issues, such as poor navigation, confusing layouts, and non-responsive designs. The main takeaway is that even small design missteps can significantly affect user experience. Therefore, always be mindful of:

Inspiration from Award-Winning Designs

We reviewed examples of award-winning websites like Spotify’s Culture Next and Edcamp Ukraine, highlighting the importance of thoughtful color use, space management, clear branding, and language. As a designer, always draw inspiration from industry leaders to:

Tools and Process

We also highlighted the importance of tools and processes such as:

Practical Tips for Aspiring Designers

To thrive in UI/UX design, consider these tips:

In conclusion, UI/UX design is not just about making things look good; it’s about crafting intuitive, accessible, and functional user experiences. The tools, tips, and insights shared in this workshop provide a strong foundation for your journey as a UI/UX designer.

Resources LInked in Slides


Introduction to Docker

Click here for the Docker workshop slides: GBM #4_ Docker Workshop - Ezri Slides.pdf

What is Docker

Docker is a platform and tool for developing, shipping, and running applications by using containerization technology. Containers allow a developer to package up an application with all of the parts it needs, such as libraries and other dependencies, and ship it all out as one package. This ensures that the application will run on any other Linux machine regardless of any customized settings that machine might have that could differ from the machine used for writing and testing the code. 

This provides consistency when working on a team where people run different operating systems.

In Blueprint we use Docker containers in several of our applications to manage different services and projects. 

Additional Resources

Introduction to Node.js

What is Node.js?

Node.js is an open-source, cross-platform, JavaScript runtime environment that allows developers to run JavaScript on the server side. It is built on Chrome's V8 JavaScript engine, and it enables the execution of JavaScript code outside a web browser. This capability makes it possible to use JavaScript for server-side scripting and building fast and scalable network applications. Node.js comes with a rich library of various JavaScript modules, which simplifies the development of web applications.

What is npm?

npm stands for Node Package Manager. It is the default package manager for Node.js and is used for managing and sharing JavaScript packages. It comes bundled with Node.js, which means when you install Node.js, you automatically get npm installed on your system. npm makes it easy for JavaScript developers to share and reuse code, and it's a vital tool for managing project dependencies.

How to Install Node.js and NVM

You can install specific versions of node individually, however we recommend making use of a tool called Node Version Manager (NVM). NVM allows you to change and install new versions of Node on your device easily. When working with multiple node projects that may rely on features from certain versions, NVM is extremely helpful.

For Mac:

If you have brew installed, you run

brew update
brew install nvm
mkdir ~/.nvm

# Using zsh
echo "export NVM_DIR=~/.nvm\nsource \$(brew --prefix nvm)/nvm.sh" >> .zshrc
source ~/.zshrc

For Windows

Credit: https://www.freecodecamp.org/news/node-version-manager-nvm-install-guide/ 

  1. Click on Download now
    In the nvm-windows repository Readme, click on "Download Now!":

    image-338

    This will open a page showing different NVM releases.

  2. Install the .exe file of the latest release

    In the latest release you'll find different assets. Click on the nvm-setup.exe asset which is the installation file for the tool

  3. Follow the Installation Wizard

Installing node and npm with nvm:

Verify your installation with nvm -v in the terminal. Once nvm is installed, you can install specific versions of node:

nvm install 20.0.0 # Installs a specific version
nvm install --lts # Installs the latest Long Term Support Version

nvm ls # Shows all the version of node installed

# Switch to a specific node version
nvm use <VERSION_NUMBER> 
nvm use 20.11.1

# Sets devices default node version to the specific version
nvm alias default <VERSION_NUMBER> 
nvm alias default 20.11.1

To verify your installation type node -v and npm -v in the terminal. 

If the instructions above don't work, check out these resources:

Software Development Crash Course

This workshop covers some tools and best practices that will help you develop software more efficiently, both independently, but especially as a TEAM. We attached the following resources for anyone who missed the workshop or would like a refresher: