Skip to content

How to Add New Change Log Entries

Jump to bottom
nickmazzi edited this page Nov 27, 2017 · 18 revisions

(0) Background Information

(1) Development Environment

(2) Get Image for Change Log Entry

  • Applicable to the image_url field.
  • Format should be Portable Network Graphics (PNG)
  • File extension should be lower-case
    • e.g. *.png
  • Image resolution should be exactly 958 x 446 pixels.
    • The thumbnail preview image will be scaled down to exactly 479 x 223.
    • Note: This requirement is too strict.
    • Width should be ~480 pixels and the height natural (flexible).
    • TODO: Need to discuss with Design and DEV teams to rectify in the UI.
  • Important: Images should be uploaded to this GitHub repository instead of cross-linking to another site we do not control to avoid broken links / images.

(3) Add Image to Local File System

  • i.e. Add image to local GitHub repository.
  • Add image to 3 locations:
    • (1) datascix/public/dev/changelog/img
    • (2) datascix/public/qa/changelog/img
    • (3) datascix/public/prod/changelog/img
  • Each location corresponds to a DevOps deployment environment for the DSX site.
  • For more details, see: About the Change Log Feature

(4) Upload Images for Change Log Entry

  • i.e. Commit image to remote GitHub repository.
  • Important: Do NOT upload any changes related to the JSON Change Log files yet (i.e. entries.json).
  • Note: This step seems premature / counter-intuitive; but, is required to validate whether the image URLs resolve correctly via the automated validation script.

(5) Add Stub Change Log Entry to YS1 DEV JSON Change Log File

	{
		"title" : "",
		"id" : "",
		"author" : "",
		"author_image_url" : "",
		"date" : "",
		"message" : "",
		"image_url" : "",
		"blog_url" : ""
	}
  • Recommended: Add the new entry to the beginning of the file (i.e. first entry) in order to arrange the entries in reverse chronological order (to mirror how the entries are presented in the DSX What's New Page).
  • Important: Do not leave a trailing comma (,) if adding the entry to the end of the file.

(6) Specify the Title

  • Applicable to the title field.

(7) Specify the ID

  • Applicable to the id field.
  • The ID must be a valid Globally Unique Identifier (GUID).
  • Go to Online GUID Generator
  • Click the "Generate some GUIDS!" button.
  • Copy the GUID value and use it for the ID value.
    • e.g. cd299019-2223-4aa3-a8a8-779b1b36b12a

(8) Specify the Author

  • Applicable to the author field.

(9) Specify the Author Image URL

  • Applicable to the author_image_url field.
  • Use the URL to an author's user profile image already uploaded to GitHub.
  • i.e. https://github.com/IBMDataScience/datascix/blob/master/public/dev/changelog/img/author_armand.jpg?raw=true
  • Important: Make sure to refer to the correct image path.
    • i.e. In this case public/dev
  • Important: Remember to add the ?raw=true query parameter to the end of the URL.
  • Important: Always use secure (HTTPS) image URLs.

(10) Specify the Date

  • Applicable to the date field.
  • The date format must be in UTC and conform to ISO 8601.
  • e.g. 2016-08-15T08:06:05.524Z

(11) Specify the Message

  • Applicable to the message field.

(12) Specify the Image URL

  • Applicable to the image_url field.
  • Use the URL to the image you uploaded to GitHub in step (4) Upload Images for Change Log Entry.
  • i.e. https://github.com/IBMDataScience/datascix/blob/master/public/dev/changelog/img/projectTabs.png?raw=true
  • Important: Make sure to refer to the correct image path.
    • i.e. In this case public/dev
  • Important: Remember to add the ?raw=true query parameter to the end of the URL.
  • Important: Always use secure (HTTPS) image URLs.

(13) Specify the Blog URL

  • Applicable to the blog_url field.
  • Blog entries are sourced from http://datascience.ibm.com/blog.
  • e.g. http://datascience.ibm.com/blog/upload-data-and-create-data-frames-in-jupyter-notebooks/

(14) Specify the Audience

  • Applicable to the audience field (an array which lists the relevant audience for this blog post)
  • A single pair of square brackets must surround the entire set of values for this field
  • If the array is left empty, it is assumed that the blog post is targeted toward all offerings (WDP wide)
  • valid values for offerings include:
    • “data_science_experience”
    • “data_refinery”
    • “data_catalog”
  • Separate offerings by commas

(15) Validate the YS1 DEV JSON Change Log File Syntax

  • Change to the datascix directory (root of local GitHub repository):
$ cd datascix
  • Validate the JSON syntax:
$ grunt jsonlint
  • Fix reported errors (if any).

(16) Validate the YS1 DEV JSON Change Log File Content

  • Important: Ensure that you have already uploaded the images for the Change Log entry in Step (4).
  • Validate the JSON content:
$ grunt urlValidate:dev
  • Fix reported errors (if any).
  • Recommended: Use a visual file comparison and difference (diff) tool to manually review your changes to the JSON file with the previous version / commit.

(17) Upload the YS1 DEV JSON Change Log File

(18) Verify Change Log Entry in YS1 DEV Environment

  • Go to the DSX What's New Page in the development environment.
  • Visually verify the new Change Log entry.

(19) Add New Change Log Entry to YP QA JSON Change Log File

  • Copy the new YS1 DEV Change Log entry to the YP QA JSON Change Log file.
  • i.e. public/qa/changelog/entries.json
  • Important: Replace the /dev/ path segment with /qa/ in the image_url property field value.

(20) Validate the YP QA JSON Change Log File Syntax

  • Validate the JSON syntax:
$ grunt jsonlint
  • Fix reported errors (if any).

(21) Validate the YP QA JSON Change Log File Content

  • Important: Ensure that you have already uploaded the images for the Change Log entry in Step (4).
  • Validate the JSON content:
$ grunt urlValidate:qa
  • Fix reported errors (if any).
  • Recommended: Use a visual file comparison and difference (diff) tool to manually review your changes to the JSON file with the previous version / commit.

(22) Upload the YP QA JSON Change Log File

(23) Verify Change Log Entry in YP QA Environment

  • Go to the DSX What's New Page in the test (quality assurance) environment.
  • Visually verify the new Change Log entry.

(24) Add New Change Log Entry to YP PROD JSON Change Log File

  • Copy the new YS1 DEV Change Log entry to the YP PROD JSON Change Log file.
  • i.e. public/prod/changelog/entries.json
  • Important: Replace the /dev/ path segment with /prod/ in the image_url property field value.

(25) Validate the YP PROD JSON Change Log File Syntax

  • Validate the JSON syntax:
$ grunt jsonlint
  • Fix reported errors (if any).

(26) Validate the YP PROD JSON Change Log File Content

  • Important: Ensure that you have already uploaded the images for the Change Log entry in Step (4).
  • Validate the JSON content:
$ grunt urlValidate:prod
  • Fix reported errors (if any).
  • Recommended: Use a visual file comparison and difference (diff) tool to manually review your changes to the JSON file with the previous version / commit.

(27) Upload the YP PROD JSON Change Log File

(28) Verify Change Log Entry in YP PROD Environment

  • Go to the DSX What's New Page in the production environment.
  • Visually verify the new Change Log entry.

Clone this wiki locally