Skip to content

lab 10

Jump to bottom
Emily edited this page Nov 29, 2021 · 66 revisions

Lab 10

Due Date

Friday November 26 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:

  1. create a reproducible, automated build
  2. use some variant of semantic versioning to precisely identify and communicate the version
  3. use git and tags to log releases in project history
  4. add "package" file(s) of some kind, identifying dependencies and which files should be included
  5. 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:

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.

Name Blog Post (URL) Your Release on the chosen Package Registry (URL)
Tuan Phong Nguyen Blog Nuget
Anatoliy Serputov Blog NPM
Ahmad Rokay Blog PyPI
Minsu Kim Blog NuGet
Roman Rezinkin Blog PyPi
Tuan Thanh Tan Blog NPM
Duc Bui manh Blog NPM
Chi Kien Nguyen Blog Conan
Kunwarvir Dhillon Blog Post npm
Jiyun Jung Blog NPM
Andre Willomitzer Blog npm link
Francesco Menghi Blog NPM
Gustavo Tavares Blog 😃 npm
Luigi Zaccagnini Blog npm
Kevan Yang Blog✨ npm
Joshua Li Blog conan
Qiwen Yu Blog PyPI
Xiongye Jiang Blog NPM
Reza Poursafa Blog NPM
Le Minh Pham Blog Post PyPI
Mizuho Okimoto Blog Post NPM
Oliver Pham Blog Post PyPI
Gus McCallum Blog Post conan
Eugene Chung Blog Post NPM
Leyang Yu Blog Post NPM
Japneet Singh Kalra Blog Post SPM
Suhhee Kim Blog Post NPM
Jun Song Blog Post NPM
Amasia Nalbandian Creating Tags and Releases using NPM nlb-ssg
Tengzhen Zhao Blog PyPI
Minh Quan Nguyen Blog npm
Hung Nguyen Blog npm
Roxanne Lee Blog npm
Thanh Cong Van Blog npm
Emily Phan Blog Nuget
Vivian Vu Blog npm
Minh Hang Nguyen Blog npm
Andrei Batomunkuev Blog PYPI
Andrew Tassone Blog Conan
Trang Nguyen Blog maven
Alex Romanova Blog npm
Clone this wiki locally