lab 6 - humphd/topics-in-open-source-2024 GitHub Wiki
Lab 6
Due Date
Friday November 1 by Midnight.
Overview
This week we are focused on managing project complexity through the use of Static Analysis tooling. Static analysis tools operate on our source code (static) vs. running program (dynamic). They help us maintain the quality of our source code by fixing formatting issues, spotting suspicious coding constructs, or alerting us to common errors. Most of us wouldn't write a document in a word processor without spellcheck, and neither should programmers write code without linters and other static analysis tools. Using these tools is critical in a collaborative project with lots of contributors. Programming is hard, and the best programmers know that they can't do it without good tools to help them.
NOTE: I assume that some of you will already be familiar with, or using some of these tools. In that case, I want you to try new tools you haven't used before instead (recommendations below).
NOTE: Please watch this week's video lecture before you start this lab.
This lab will help you learn to work with and set up the following:
- an automatic source code formatter
- a source code linter
- command-line or project build scripts to run your static analysis tooling
- editor/IDE integration of your static analysis tooling
- write contributor documentation to setup and use your tools
For this lab you will are asked to work on your own TIL project repo. However, you are free to collaborate and help each other as you do these steps. Make use of the course's community on Slack and GitHub.
Step 1: Create a Branch
Create a branch for your work. All steps in this lab should be done on this branch, and you are encouraged to commit regularly (e.g., after you get each step working, commit). When you are done, you'll be asked to squash all of your commits and merge to your default branch.
Step 2: Create a CONTRIBUTING.md File
Create a new file, CONTRIBUTING.md, in the root of your project. Move all sections of your README.md file that deal with setup and development to CONTRIBUTING.md. When you are done the README.md file should discuss what your project is and how to *use it, and CONTRIBUTING.md should discuss how to develop it. There are various templates and generators for creating your own CONTRIBUTING.md if you need help.
We will be adding more details to CONTRIBUTING.md in the next steps.
Commit all the changes you've made to git.
Step 3: Add a Source Code Formatter
Automatic source code formatters (also known as beautifiers or "pretty printers") take source code as input and produce properly formatted output. Their goal is to establish a common format for all source code in the project.
Pick a source code formatter for your language and add it to your repo. Here are some suggestions, but you are free to use another that you want to try:
- JavaScript Prettier or Oxc
- Java Google Java Format
- Python Black or Ruff Formatter
- C# CodeFormatter or Reshaper or dotnet-format
- Go gofmt
- Rust rustfmt
- C++ clang-format
After you've picked a formatter, do all of the following:
- Read the docs for your formatter. There will be detailed instructions on setup and configuration. Make sure you've read them before you proceed.
- Setup the formatter in your project. This might mean adding files, packages, and settings.
- Often we configure settings for how the output should look (e.g., how to indent, where to put whitespace). Choose any settings and add them to the formatter's configuration. Ideally you shouldn't change the defaults if you can avoid it. Automatic source code formatting means letting a tool decide instead of using personal preference, so everyone hates some parts of how the code looks, but generally we all agree it's better.
- Add any files or folders to be ignored. You shouldn't format all the files in your project, only the ones you are developing.
- Create a simple "one-step" solution for running your formatter on the entire project from the command line. This could be an
npmscript, a shell script, or some other method common to your language or package manager. You must end up with a command you can run at the command line that calls your formatter. - Run the formatter via the command line on your entire project's source code. Look at everything it's changed and make sure things are OK, then commit the changes.
- Make sure your project still works! Did you break anything in your program by making these changes? If so, fix them now and re-run the formatter until everything works again.
- Document how to use the formatter and its command line "script" in
CONTRIBUTING.md.
How much did the formatter change your code? Were there are lot of indentation and formatting issues? Remember this for your blog post.
Commit all the changes you've made to git.
Step 4: Add a Linter
Linters help us spot common and subtle mistakes that all programmers make, or help us avoid certain code patterns that lead to bugs. We want to make it easy for ourselves and new developers joining our project to not introduce bugs or bad code.
Pick a linter for your language and add it to your repo. Here are some suggestions, but you are free to use another that you find:
- JavaScript ESLint or Oxc
- Java SpotBugs
- Python Flake8 or PyLint or Ruff
- C# StyleCopAnalyzers
- Go golint or golangci-lint
- Rust rust-clippy
- C++ clang-tidy
After you've picked a linter, do all of the following:
- Read the docs for your linter. There will be detailed instructions on setup and configuration. Make sure you've read them before you proceed.
- Set up the linter in your project. This might mean adding files, packages, and settings.
- Often we configure various linting rules (e.g., what to check for and what to ignore). Choose any settings and add them to the linter's configuration.
- Add any files or folders to ignore. Not everything in our project can or should be linted.
- Create a simple "one-step" solution for running your linter on the entire project from the command line. This could be an
npmscript, a shell script, or some other method common to your language or package manager. - Run the linter via the command line on your entire project's source code, fix the warnings and errors it finds, and repeat the process until there are no issues. Once this is done, commit the changes.
- Learn how to add one-off lint ignore comments to your code. Often there are specific lines of code where, for one reason or another, we can't fix a linting error. Instead, we need to tell our linter to ignore this line, or ignore this whole function, or ignore this whole file. Make sure you know how to do this, and use it if necessary.
- Make sure your project still works! Did you break anything in your program by making these changes? If so, fix them now and re-run the linter until everything works again. It's usually possible to disable linters via special comments in your source code, but it's a better idea to fix the code so it doesn't have any issues. Rewrite any code that the linter says is problematic.
- Document how to use the linter and "script" in
CONTRIBUTING.md.
How many errors or warnings did the linter produce for your code? How hard was it to fix them all? Remember this for your blog post.
Commit all the changes you've made to git.
Step 5: Editor/IDE Integration
Running static analysis tools at build time (i.e., using our scripts) is great because we can automate it. However, it's also nice to provide a way to integrate them into our editor or IDE so that we get the benefits while we are writing code. An automatic source code formatter can be run whenever we save a file. Similarly, we can have a linter running continuously and underlining errors or warnings as we type. This lets us fix issues as soon as make them, and helps us produce better code.
We could set up our own personal editor to work the way we like, but then new contributors wouldn't have the same development environment as we do. Instead, it's common to create configuration files and folders in our project that get read by the user's editor and and applied automatically. For example, Visual Studio Code settings can be placed in a .vscode/ folder.
Research how to integrate your Source Code Formatter and Linter into your editor. I highly recommend using VSCode, but you can use which ever editor is most common to your language. Add any necessary configuration folders, extensions, and files to run your formatter when the user save's their code. Also, integrate the linter so that warnings and errors are automatically shown.
Both steps will likely involve adding plugins or add-ons to your editor, and this may also be something that you can include in a configuration file.
Once you have this working on your own computer, document how to get it working on a contributor's machine in CONTRIBUTING.md. NOTE: prefer using automatic configuration files over manual instructions that people have to do. The more you can automate this, the more likely it is that people will use it.
Commit all the changes you've made to git.
Step 6: (Optional) Add a Git Pre-Commit Hook
If you're still up for a challenge, try to setup a git pre-commit hook to run your source code formatter on any changes that are being committed. This will help developers not forget to run the formatter before they submit any changes or make a pull request. The process for creating a git hook will be slightly different for each language or platform, so do some research.
Step 7: Squash, Commit, Merge, Push
When you are done making code changes, rebase and squash your commits to a single commit. Merge this with your main branch and push it to your origin.
Make note of the git commit URL for the work you did on this lab.
Step 8: Write a Blog Post
When you have completed the required steps above, please write a detailed blog post. In your post, discuss the following:
- Which tools did you choose? Why did you choose them? Provide links to each tool and briefly introduce them.
- How did you set them up in your project? Be detailed so that other developers could read your blog and get some idea how to do the same.
- What did the tools find in your code? Did you have to fix a lot of issues?
- How did you get the tools to run from the command line?
- How did you integrate the tools with your editor/IDE?
- What did you learn from the process?
Submission
When you have completed all the requirements above, please add your details to the table below.