Preparing an OED Release
In preparing for an OED release, the following steps should be followed:
- Releases should correspond to a Milestone for the project.
- Announce to the Developer discussion board so everyone can look over the proposed release.
- Review the Milestone for this release to make sure all issues are complete or reassigned.
- See if there are any package or security issues that need to be addressed.
- Prepare the help 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):
- Make sure all changes are done for the previous release and put in the OED repo for the main branch.
- Update your clone from the the main branch in OED repo. You can do this on your GitHub website or "git
pull from" 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.
- 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).
- 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.
- Duplicate the previous release's help directory into the new release directory. For example, copy
help/v0.6.0 to help/v0.7.0.
- Unfortunately, you need to manually update the links to go from the previous release to the new release.
In the new help 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 help 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 below
<a href="../v0.6.0/{{page.name}}">OED version 0.6.0 Help</a>
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 below
<a href="../v0.6.0/{{page.name}}">OED version 0.6.0 Help</a>
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.
- Update the help pages to reflect the new release. Be careful to do new screenshots if the look of OED
has changed.
- Commit the changes.
- Push the changes to your fork.
- 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.
- 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.
- 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.
- Do extensive running and testing of OED in a web browser. When possible, test in all major web browsers.
- 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.
- Create the GitHub release following the steps in GitHub
Managing releases in a repository. Note you can save as a draft for later release.
- Add info about release to an OED news items and release pages on the website.
- Celebrate.