Looking Ahead

  • Release Notes (due end of week 10)
  • Final Presentation (due end of week 10)

Brief Discussion of “Release Notes”

At the end of the legacy code phase, each team will be required to submit “release notes” for all of the features they added to the main branch (i.e. the difference between their main branch, and the main branch of the starter code for the project.)

The email below is a sample of what “Release Notes” looks like for a production application. It’s an email to Prof. Mattanjah deVries with an update on the latest new features for HappyCows from a release last summer. Please take a moment to look it over.

In professional software development, these are typically a bit more formal–our setup is still a bit more informal, but the idea is the same: when there’s a new release of the software into production, you want to inform your users about the main changes they will see. This serves at least two purposes:

  • Functional: These messages help them to be aware of, and use the new functionality. Customers can’t take advantage of new features if they don’t know about them.

  • Marketing: If you are running a software business, you are always concerned about “churn”, which is the business term for when a paying customer stops paying you, and starts giving money to your competitor instead. These messages need to convey to your customers that you have heard their concerns, and care about making their lives easier, more fun, less stressful—whatever the purpose of the app happens to be. As we move into the legacy code phase of the course over the next few days, your PR descriptions will be the source material for these release notes for either HappyCows or Gauchoride, so it’s important that they be written well. This is why we ask for screenshots, etc. and that the PR descriptions include a description of new features not just from the programmer/developer perspective, but from the end-user perspective.

Sample Release Notes

---------- Forwarded message ---------
From: Phill Conrad 
Date: Wed, Aug 9, 2023 at 9:28 AM
Subject: Happy Cows new release
To: Mattanjah de Vries 

Hi Mattanjah:

I’ve deployed the latest changes to the production version at https://happycows.dokku-00.cs.ucsb.edu/

Here’s a summary of changes:

  1. There is an instructor reports option on the admin menu. To see an instructor report, select Instructor Reports from the admin menu, like this:

    image

    Then, you’ll see a page like this one, which shows all available reports. (We’ll cover how to generate a report in a moment; that’s done on the jobs menu. Later on, we can add a feature so that these are generated automatically on a schedule; right now, it’s on demand.)

    image

    To see a specific report, click on the “View Report” button.

  2. The page where an Admin can view a report looks like this.

    image

    • There’s a button to take you back to the list of reports.
    • At the top of the page is all of the information we have about the commons itself.
    • Under “Farmers” is a list of all of the farmers in the commons, and data on each one.

    There is also a “Download as CSV button” that will allow you to download the farmers part of the report as a CSV file that you can open in Excel, Google Sheets, or any other application that accepts CSV files.

    At the moment, only the farmer data is included in the CSV file. If it would be useful to be able to download the commons level data too, let us know; we could include it in the same file, or in a different one.

  3. Manage Jobs page now has option to produce instructor reports. To generate an instructor report, go to Manage Jobs

    image

    Then, select either Instructor Report (which produces a report for every commons), or Instructor report for specific commons:

    If you choose “Instructor Report for specific commons” it looks like this. Select the commons for which you want a report, and click Submit:

    image

    Then watch under job status until the report is finished:

    image

    Then, navigate to the page for instructor reports, as shown above.

  4. There is also now the job that can set all cows in a commons to have the same health value, increasing or decreasing as you see fit. It is accessed from Admin / Jobs

    image

    Then Set Cow Health for a Specific Commons

    image

    Choose a commons and a new health value, and click Set Cow Health.

    image

    Then monitor the job on the jobs page:

    image

    When finished, the bottom of the output will look like this; the words Cow Health has been set! signify that the job is finished, as well as the word Complete on the status at the top

    image

    image

  5. Finally, one change you may or may not have noticed, but it turns out to be important: the Admin Jobs page used to show the output from all jobs since the beginning of time.

Since we’ve had over 1900 jobs since we launched this instance of the Happy Cows app, that page was starting to load very, very slowly, and be unusable, especially on slower machines. We’ve reorganized this page so that it only loads the most recent 10 jobs, most recent first, and then there are “next” and “previous” buttons to be able to move forward and backwards if there is a need to see older jobs logs.

image

That’s what we have for this release. Let us know what new feature you’d like us to prioritize.

In a separate email, I’ll send you a list of what we have on our list right now, but we always want to prioritize what you think is important for making the game better.

Regards,
Phill

PRs that went into the release notes above

For reference, as you look at the release notes above, here are the PRs that went into these.

You may like to see how the PR descriptions were summarized into the release notes below. As you look at this, you’ll see that some PR titles/descriptions are better than others (I wrote pretty much all of them, so I’ll be the first to acknowledge that some of them are pretty good, and others are not so great.)

A question to ponder: What is true about the titles/descriptions that are better, and what makes them better?

Final Presentation

TO DO: fill in details here.