lab 10 - Seneca-CDOT/topics-in-open-source-2022 GitHub Wiki
Lab 10
Due Date
Friday November 25 by Midnight.
Overview
This week we are looking at software releases and getting our code into the hands of users. GitHub is great for developers, but users don't want to have to clone and build your project to run it locally. We need to provide a release that can be easily installed and run.
This lab will help you learn to work with and set up the following:
- general concepts and terminology of software releases
- git tags
- package managers
- user testing
For this lab you will are asked to work on your own SSG project, but you're welcome to help each other as needed.
NOTE: this final lab provides fewer defined steps and requires more research on your part. This is partly due to the fact that different languages and platforms have different approaches and technologies (i.e., there isn't a simple answer to "how do I release my code?"), and partly as a way for me to test your skills as we wrap up our time together in the course. Remember that open source is fundamentally about community, and you can and should collaborate with your peers on a solution.
Step 1: Choose a Package and Release Method
Modern software releases rely on package managers and centralized package repositories. Each technology ecosystem has a slightly different way of doing it, but the concepts are the same:
- create a reproducible, automated build
- use some variant of semantic versioning to precisely identify and communicate the version
- use
gitand tags to log releases in project history - add "package" file(s) of some kind, identifying dependencies and which files should be included
- upload to a central repository for shared hosting of the release
Depending on the language and ecosystem you are using, here are some recommended approaches to creating your release:
- Node.js: use npm
- Python: use PyPI or poetry
- Java: use Maven Central
- C#: use NuGet
- Go: use pkg.go.dev
- C++: use one of vcpkg or conan or build2
- Rust: use crates.io
NOTE: If you need/want to use something other than these, that's also fine. Please speak with me to discuss your thinking. It's probably OK, but I want to help you avoid any problems.
Once you have made your choice, begin reading the docs for your chosen package format and registry.
Step 2: Implement Packaging Steps
Based on your research in step 1, begin to implement your release requirements. This may mean adding more to your build system, writing scripts, creating new files, moving existing files into a new structure, adding dependencies, etc.
As you work, keep track of everything you needed to do in order to setup the necessary requirements for your release. These steps, along with all your research and learning, should all go in your final blog post.
Step 3: Tag your Release
Refresh your memory about how git tags work. While we use branches to record our position in a moving line of development, tags allow us to fix a point in the past that we can easily revisit in the future. We want to be able to easily find the 1.0.0 version of our code, as well as the 1.0.1 version, and neither should ever change once we've made them.
Practice creating some tags. To begin, try creating an Annotated Tag for v0.9.0. Later, when you do your actual release, you can use v1.0.0.
When you are done creating tags on main you can use git push --follow-tags to push them to GitHub.
Step 4: Do a Release
Once you have your release process figured out, have setup your project to support your chosen package registry, and understand how to tag, it's time to do a release.
Create a v1.0.0 release of your project, and submit it to your chosen package registry. If you make a mistake, don't panic! Simply fix your mistake and do another release using a PATCH update (e.g., v1.0.1).
Do as many releases as you need to get this right.
Step 5: Update Your Docs
Now that your software can be used via a package registry, you need to update your README.md file to give full instructions on using your code. Re-read your README.md and update all the information about how to download and install your project from a user's perspective.
To do this, try setting up a new project that uses your code via the package registry. Make sure you are able to get it working locally using your instructions.
Once you are done, commit and push these changes to your origin.
Step 6: User Testing
Now it's time to see what happens when someone else tries to install and use your code via the package registry. Find someone who is willing to test your project. It can be someone in the course, or a friend not taking this course. I would recommend that you choose a fellow developer, though, so you don't have to explain the basics of using your chosen programming language, tools, or ecosystem.
Setup a call with your friend over MS Teams, Zoom, or some other communication platform and get them to share their screen with you. Now point them at your README.md file. Ask them to read the instructions and try to follow what they say. Also, ask them to narrate what they are doing as they do it so that you can take notes. Their goal is to use your project on their machine.
NOTE: try to observe but not guide them beyond what your README says. If the README is unclear, you can help them, but make notes about problems they encountered and corrections you need to make.
When they are done, ask them for feedback about the process and any things that they found difficult or missing. Make notes so you can update your README.
Step 7. Update Developer Docs to Include User Testing Feedback
Based on the feedback you got in the previous step, update your README so that it includes the necessary information a user would need to install and use your project. You may also find that you need to update your release to include files, dependencies, or otherwise modify what a user installs.
When you have updated your README, push it to GitHub.
Step 8. (Optional) Automate your Release Process with GitHub Actions
Just as you did with automating your tests, you can also automate your release process via GitHub Actions. Depending on your chosen package registry, research and implement the steps necessary to automate a new release whenever you push a new tag to your main branch.
Step 9: Write a Blog Post
When you have completed all of the required steps above, please write a detailed blog post. In your post, discuss the following:
- Which release tool and package registry did you choose? Provide links to everything you mention.
- What was the process for creating a release? Be detailed so that other developers could read your blog and get some idea how to do the same.
- What did you learn while doing your release? Did you have any "aha!" moments or get stuck?
- How much did you have to alter your code, files, build, etc. to use the chosen package format and registry?
- How did the User Testing session with your partner go? Describe what it was like, where they got stuck, and how you corrected the problems.
- How do users install and use your project now that it has been released? Provide links and some instructions.
Submission
When you have completed all the requirements above, please add your details to the table below.