Conventions - Agile Software Development & DevOps
All student’s must adhere to the following conventions when doing work in the course. These conventions will make your code more readable, more easily maintainable, more streamlined and accountable, and consistent with the work and expectations of other students and instructors.
Use a team messenger app for all communication
One of our learning objectives is to become familiar with effective use of team messenger systems, such as Slack, Discord, or Microsoft Teams, for communication within a group, instead of email. Familiarize yourself with our guidelines for using Discord. Do not send email unless there is an emergency.
Use one email address for everything
This course depends upon multiple online resources. For example, we may use Zoom for lecture, Google Forms for quizzes, Git & GitHub for project work, etc. We reconcile your work across these systems using your email address. Use only one email address to log into all services used in this course… and let us know what that email address is.
Use one username for git & GitHub
Git and GitHub are two different systems. To ensure accountability, set your git username to match your username on GitHub. Also be sure to remove any Name setting in your GitHub profile, which is sometimes used in place of your username and creates confusion and lack of accountability.
Use single-line git commit messages
When committing code to any repository using git, use only single-line commit messages.
To help enforce this rule, set up a “hook” – a script that runs with every commit – to validate the commit message and reject multi-line commit messages. Copy this hook created for you for this purpose into each of your repositories (if not already present) and follow the instructions in the comments to set it up, make it executable, and activate it as a git “commit-msg” hook for your repository. Since these hooks run on a developer’s local machine, this has to be done by every team member once for each repository.
Turn off git rebasing
git has two ways of completing the git pull action: merge and rebase. Turn off rebasing for all repositories in this course. This will prevent you from accidentally rewriting the history of your project.
Use Visual Studio Code for editing and git integration
Use Visual Studio Code (VSCode) as your code editor. Use VSCode’s integrated Terminal when command shell access is required. Use VSCode’s integrated git support for all git operations.
You are forbidden from using GitHub Desktop, GitKraken Desktop, or other tools that perform git actions on your behalf for any work in this course. Perform those actions using VSCode’s built-in git support or from the command line instead.
Use a Linux/UNIX-compatible command shell
When running commands from the command shell, all students must use Linux/UNIX commands.
macOS users are free to use the built-in zsh shell, or other macOS-compatible shell. Use VSCode’s integrated Terminal, not macOS’s separate Terminal app.
Windows users must install a POSIX-compatible shell, either Windows Subsystem for Linux (WSL) or Git Bash (part of Git for Windows), and use that instead of the built in cmd or PowerShell shells. Use VSCode’s integrated Terminal, which can open a WSL or Git Bash shell. If using WSL, make sure it is configured to be compatible with Docker.
-
If using WSL, set it to use WSL version 2 by default by running the command,
wsl --set-default-version 2. -
To set Git Bash or WSL as the default terminal shell within Visual Studio Code on Windows, you can try to follow the instructions in the second answer here by Mahade Walid and edited by FruityOatyBar (ignore the first answer, which is outdated).
Follow a “feature branch workflow”
When working with others in a single repository, unless instructed otherwise, follow a “feature branch workflow”. This means making code changes in a separate branch, not directly in the main/master branch. When done, push that branch to GitHub and then create a “pull request” on GitHub.
A pull request is a request for a teammate to review your code before merging your changes into the main/master branch. Communicate with your teammates and ask them to review your pull request and approve it once they have reviewed your work and found it to be of excellent quality, with no errors or omissions.
If your work is not approved by a teammate, discuss his or her concerns, make any necessary changes on your local machine in the same branch, push those changes to GitHub again, and ask the teammate to review the pull request again and approve it if good.
Follow standard Javascript code conventions
While there is no one set of conventions for the style with which Javascript code should be written, the ESLint linter and Prettier code formatter can help standardize how you and your teammates write code. Fortunately, there are extensions for Visual Studio Code for both of these tools. Follow our instructions for installing and configuring these extensions.