How to Add New Change Log Entries

(0) Background Information

• About the Change Log Feature

(1) Setup Development Environment

• Development Environment Setup Instructions

(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 DEV Copy of JSON File

• i.e. public/dev/changelog/entries.json
• Stub entry template:

	{
		"id" : "",
		"title" : "",
		"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 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

(7) Specify the Title

• Applicable to the title field.

(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.
  • Otherwise, users will encounter security-related web browser exceptions when loading the DSX Change Log / What's New page.
  • e.g. Loading mixed (insecure) display content "http://datascience.ibm.com/blog/content/images/2016/08/wRdxWjmL4w.gif" on a secure page.

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