Releasing OED

In preparing for an OED release, the following steps should be followed:

1. Releases should correspond to a Milestone for the project.
2. Announce to the Discord developer channel so everyone can look over the proposed release.
3. Review the Milestone for this release to make sure all issues are complete or reassigned.
4. See if there are any package or security issues that need to be addressed.
5. Prepare the documentation pages for new release in the OpenEnergyDashboard.github.io repo. These steps assume you have forked this repo onto your own account and are working from that fork (probably in a local clone):
   1. Make sure all changes are done for the previous release and put in the OED repo for the main branch.
   2. Update your clone from the the main branch in OED repo. You can do this on your GitHub website or git fetch and merge of the main branch of the OED repo (generally referred to as upstream as where the fork came from) into your local main in Visual Studio. If you do it on the GitHub website then you will need to pull it down into your local clone.
   3. Create a new branch from the one you just updated for the new release. For example, if going from version 0.6.0 to 0.7.0 then branch main to create the branch v0.7.0. Commit these changes and the push them out to your fork (will probably require you to accept publishing the new branch if in Visual Studio and do it to your origin/forked copy).
   4. To allow testing of the new branch on your fork, go to the OpenEnergyDashboard.github.io repo on your GitHub account in a web browser. Click on the "Settings" tab and then click on the "Pages" choice on the left side of the page. Under "Source", use the "Branch" dropdown menu to choose the new branch that you just pushed/published. This should cause you to see this branch when you go to https://<your GitHub ID>.github.io/OpenEnergyDashboard.github.io where you replace with your id.
   5. Duplicate the previous release's documentation directory into the new release directory. For example, copy help/v0.6.0 to help/v0.7.0.
   6. Unfortunately, you need to manually update the links to go from the previous release to the new release. In the new documentation directory (e.g., help/v0.7.0) edit each change listed below to update the version (e.g., v0.6.0 to v0.7.0) so do the following:
      • Globally change the documentation links, e.g. help/v0.6.0 to help/v0.7.0. You can do this in the global search box in Visual Studio. Note it is important to prefix it with help/ so you don't edit other references to the version.
      • edit _layouts/admin.html to add a line above
        <a href="../v0.6.0/{{ page.name }}">OED version 0.6.0 Help</a>
        so it now has the line
        <a href="../v0.7.0/{{ page.name }}">OED version 0.7.0 Help</a>
        
      • Similarly, edit _layouts/help.html, to add a line above
        <a href="../v0.6.0/{{ page.name }}">OED version 0.6.0 Help</a>
        so it now has the line
        <a href="../v0.7.0/{{ page.name }}">OED version 0.7.0 Help</a>
        
      • Edit help/v0.7.0/_version.html to update the version shown, e.g., 0.6.0 to 0.7.0.
   7. Update the help pages to reflect the new release. Be careful to do new screenshots if the look of OED has changed.
   8. Commit the changes.
   9. Push the changes to your fork.
   10. Check the changes work on your GitHub account (see above). When all is okay, create a pull request to put these changes into the OED GitHub pages. After it is merged, verify all still works okay.
   11. Note that if you find an issue with documentation included in previous releases then you will need to manually edit earlier versions to include this change, as appropriate.
6. Do the final steps to prepare for the new version:
   • Edit package.json to change the line ""version": "0.6.0"," to the version number you are about to release. Assuming you are going to version 0.7.0 (as in the next step for migrations) then it becomes: "version": "0.7.0",. You also need to edit package-lock.json to make a similar change as migrations do not update this file given changes in package.json.
   • Assuming you have a migration of the database for this release, edit ``src/server/migrations/registerMigration.js`` to add a line that corresponds to the migration folder in ``src/server/migrations``. For example, if you are migrating from 0.6.0 to 0.7.0 and have the directory ``src/server/migrations/0.6.0-0.7.0`` then you add the line ``require('./0.6.0-0.7.0')`` remembering to put a comma at the end of line on the next-to-last (penultimate) line with a require." You should put the migration listings in order of their release number. Note if the last release did not have migrations then you need to use that as the previous version number so that the migration directories (and the next step) do not have gaps in the ranges or the migration will fail.
   • Create the index.js file in the migration you are adding, e.g., ``src/server/migrations/0.6.0-0.7.0/sql/index.js``. You can look at one for a previous migration to see what to do. First, you need to edit the lines so the "fromVersion" and "toVersion" correspond to the version you are going from to the version you are going to. In the running example that would be "fromVersion: '0.6.0'," and "toVersion: '0.7.0',". You now need to add a line inside "up: async db => {" for each migration file you have in this migration subdirectory. An example of a line would be:
     await db.none(sqlFile('../migrations/0.6.0-0.7.0/sql/meter/some_meter_change.sql'));
     where you need to make sure there is one line for each file that actually exists for this migration.
7. Do extensive running and testing of OED in a web browser. When possible, test in all major web browsers.
8. Verify the upgrade from a previous version works using the directions on the latest version of the Admin Upgrading help page. This normally means starting from the previous version on a server. If not already there see the Admin Installation help page on doing this where you will need to load in test data, add groups, etc. before upgrading to be sure the database migrates correctly. From the previous version you do the upgrade. After the upgrade make sure everything works correctly including the new features.
9. Create the GitHub release following the steps in GitHub Managing releases in a repository. Note you can save as a draft for later release.
10. Add info about release to an OED news items and release pages on the website.
11. Celebrate.