lab 7 - Seneca-CDOT/topics-in-open-source-2022 GitHub Wiki
Lab 7
Due Date
Friday November 4 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: 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 SSG project. 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.
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 SSG's 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 Standard
- Java Google Java Format
- Python Black
- 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.
- Add any files or folders to be ignored.
- 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. - Run the formatter via the command line on your entire project's source code and 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 "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 "silly" mistakes that all programmers make, or help us avoid certain code patterns that often 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 SSG's language and add it to your repo. Here are some suggestions, but you are free to use another that you find:
- JavaScript ESLint or Standard
- Java SpotBugs
- Python Flake8 or PyLint
- 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.
- Setup 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.
- 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. - 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.
- 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 the 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 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.