Skip to content

How to Add New Change Log Entries

Jump to bottom
Mike Pawlowski edited this page Jan 12, 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 479 x 223 pixels.
    • 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 File

	{
		"title" : "",
		"id" : "",
		"author" : "",
		"date" : "",
		"message" : "",
		"image_url" : "",
		"blog_url" : ""
	}
  • 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 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

(10) Specify the Message

  • Applicable to the message field.

(11) 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.

(12) 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/

(13) Validate the YS1 DEV JSON 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).

(13) 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).

(14) Upload the YS1 DEV JSON Change Log File

(*) 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.

Clone this wiki locally