Creating a General Release Note

From Calidus HUB
Revision as of 15:55, 15 July 2025 by Anw (talk | contribs) (Updated)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

This is a guide to using the general release note format.

Overview

Note Note: This should not be used for WMS and CTMS ERs and Patches, or EPOD Server or Android release notes, or WCS release notes. Each of these have very specific requirements for the release notes and have their own templates.

However, this format can be used for formal release notes for other products such as

  • TCM
  • Bay Diary
  • ToC
  • VEhub
  • TCM
  • Calidus MCS
  • Portal (although a more specific version exists solely for Portal, the format is based on this one and therefore may be used as a template.

Creating a new Release Note

Note: You must be logged in.

Go to the main page and click on Create New Pages from Templates

Find the General Release Note section.

Enter your product release note in the box. The standard naming convention is:

  • REL Sys Version Client-Optional
    • e.g. REL MCS 2.03.01
    • e.g. REL Portal 11.03.01 CTY


Note Note: Choose your document titles well - these will be included in the printed/output PDF documents on the top of every page, and therefore should be very descriptive - examples are provided of the standards being followed.

  • MCS
  • ASSIST
  • TCM
  • VEhub
  • Vision
  • PORTAL
  • Bay Diary
  • TOC

Click Create New General Release Note

The system will take you to the page with everything you need for creating a release note, editing in source mode.

You can edit in source mode, or you can flip to visual editing. Either:

  • Click Create instead of Create Source at the top
  • Click the pencil icon and select Visual Editing.

You will then be editing in Visual Editor.

Source Editing

Change the following at the top of the page

  • #vardefine:System - the System e.g. PORTAL, MCS, TCM, TOC, Bay Diary}}
  • #vardefine:SystemVers - the major system version
  • #vardefine:ERPatch - the minor system version
  • #vardefine:ERNumber - the revision number
  • #vardefine:Date - the build date DD/MM/YYYY
  • #vardefine:Client - optional - the client, if this is a client-specific build. Otherwise leave blank

Note Note: Choose your product/system well - the Products chosen when creating the new page should be used from the list below. This is because the Assist system automatically categorises all pages into sub-categories by Product based on your entry. Choosing the right one means that this is automatic and will be most useful to those using the system.

  • MCS
  • ASSIST
  • TCM
  • VEhub
  • Vision
  • PORTAL
  • Bay Diary
  • TOC

This will set the title, system, version, and Build number automatically from what was entered. If you have Preview turned on, it will change a few seconds after you make the changes.

You can then continue editing, adding rows to the different sections, adding or removing unwanted sections, etc.

When complete, enter an editing summary at the bottom of the page and click Save Changes.

Visual Editing

Under the header, greyed out, there are 3 variables, used by the page for the titles, version and (importantly) the categorisation of the page. They look like greyed out puzzle pieces.

  • #vardefine:System
  • #vardefine:SystemVers
  • #vardefine:ERPatch
  • #vardefine:ERNumber
  • #vardefine:Date
  • #vardefine:Client

Click on the variable to change and click the Edit button - an edit popup will show. Enter the value you want here:

  • #vardefine:System - the System e.g. PORTAL, MCS, TCM, TOC, Bay Diary}}
  • #vardefine:SystemVers - the major system version
  • #vardefine:ERPatch - the minor system version
  • #vardefine:ERNumber - the revision number
  • #vardefine:Date - the build date DD/MM/YYYY
  • #vardefine:Client - optional - the client, if this is a client-specific build. Otherwise leave blank

This will set the title, system, version, and Build number automatically from what was entered. It won't change immediately - it will change when you save the page.

You can then continue editing, adding rows to the different sections, adding or removing unwanted sections, etc.

When complete, you can click Save Page. You will be prompted to enter an editing summary - enter one and click Save Page.

Sections

Note Note: If any sections are not required, remove them. There should however always be at least one of the first to sections:

  • Released Modules.
  • Resolved Issues/Changes.


The programs included in the patch should be added to the Release Modules section.

  • Enter the following
    • Module - if there are multiple modules (e,g, Server, Web Client, Webservices) indicate that here
    • Program Name - a unique reference if applicable to the screen/program being released
    • Internal Ref - the DevOps case
    • Client Ref - the SalesForce case if applicable
    • Remarks - a description of the problem and solution.
  • If there are database scripts required, add the ID of the script here

Any issues resolved and changes made should be added to the Resolved Issues/Changes section.


If there are new screens and they have been added to a default menu, add the details to the New Screens section. This section is not required if you are using the Released Modules section above.

Note that this is NOT a client specific release note - if the customer has bespoke menus, they are not reflected in this release note.

  • Menu - the menu/submenu added. Make then italicised.
  • Screen ID - any ID or name if there is one. Make them italicised.
  • Screen Description - the screen name or description, or purpose.


Should any new functionality require access control, then this should be entered in the New Access section. This section may be omitted if there is no access control on modules or screens mentioned in this release note.

  • Access Type - where the access is sourced from. This could be functional access, tab access, imports, exports, fields on a screen, user permissions/settings, user types, existing or new system parameters, etc.
  • Name - the unique name
  • Description - description of what this does.


Should there be any new or applicable parameter, rule or registry setting or value that directly affects the functionality being released, enter the information in the New Parameters & Settings section.

  • Parameter Name - The parameter name as seen in the screens.
  • Config Level - The parameter type, level, table on which it is location, screen where it can be found, etc.
  • Description - A description of the parameter or setting.
  • Setting Values - the values that may be set for this parameter.


If there is any other system release known to be required for this functionality to work, this next Warning section should be left in. Note that, if the release number of the other systems is known, then reference it directly here. Further, if you have release notes created for this release ER or PATCH, then include them as a link e.g. [[ER CTMS 047-001]] in source editing or CTRL-K ER CTMS 047-001 in visual editing.

Result

Your page will be created. The categories will be set from the variables entered as well.

Assuming we entered the following

  • #vardefine:System - MCS
  • #vardefine:SystemVers - 2
  • #vardefine:ERPatch - 03
  • #vardefine:ERNumber -01
  • #vardefine:Date - 15/07/2025
  • #vardefine:Client - blank - we should not in most of not all cases be building customer-specific release notes.

The title will default to:

  • RELEASE NOTE- MCS
  • Date: 15/07/2025    Ref: REL MCS 2.03.01

The categories will default to:

  • MCS RelNote
  • REL MCS 2.03

Creating a New Patch Category

At this point, if this is a new product/major/minor version, the specific product/major/minor category will not exist - on the right of the page, the category will be red (in this example REL MCS 2.03).

You should click this link - you will be taken to editing the new category. You need to add this to the product's Release Notes category:

  • Source editing
    • Enter [[Category:MCS RelNote]] into the source editing box, enter a summary comment and save.
  • Visual editing
    • Click the 3-line menu, click Categories and start typing MCS RelNote - the category will be shown. Select it then click Apply Changes. Enter a summary comment and save.

Note that this is just an example - use your correct product ID, not MCS. See the list above.

Note that if this category already exists, you don't need to do this.

Now, if you go to category "MCS", you will see the sub categories. If you go to category "MCS RelNote", you will see a sub category, in this example "REL MCS 2.03". You can see release notes applied to this product/major/minor version in one place. Example below:

  • MCS RelNote
    • REL MCS 2.03
Retrieved from ‘https://calidusassist.adcservices.apteancloud.com/calidus-assist/OBS/index.php?title=Creating_a_General_Release_Note&oldid=14473’