development/release-notes/AndroidXMarkdown.py - platform/frameworks/support - Git at Google

 #!/usr/bin/python3
 #
 # Copyright (C) 2020 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
 #      http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #

 from ReleaseNoteMarkdown import *
 from GitClient import CommitType, getTitleFromCommitType, getChangeIdAOSPLink, getBuganizerLink

 class CommitMarkdownList:
 	"""Generates the markdown list of commits with sections defined by enum [CommitType], in the format:

 		**New Features**
 		- <[Commit.summary]> <[getChangeIdAOSPLink]> <[getBuganizerLink] 1> <[getBuganizerLink] 2>...
 		**API Changes**
 		- <[Commit.summary]> <[getChangeIdAOSPLink]> <[getBuganizerLink] 1> <[getBuganizerLink] 2>...
 		**Bug Fixes**
 		- <[Commit.summary]> <[getChangeIdAOSPLink]> <[getBuganizerLink] 1> <[getBuganizerLink] 2>...
 		**External Contribution**
 		- <[Commit.summary]> <[getChangeIdAOSPLink]> <[getBuganizerLink] 1> <[getBuganizerLink] 2>...
 	"""
 	def __init__(self, commits=[], forceIncludeAllCommits=False):
 		self.forceIncludeAllCommits = forceIncludeAllCommits
 		self.commits = commits

 	def add(self, commit):
 		self.commits.append(commit)

 	def getListItemStr(self):
 		return "- "

 	def formatReleaseNoteString(self, commit):
 		if commit.releaseNote != "":
 			releaseNoteString = commit.releaseNote
 		else:
 			releaseNoteString = self.getListItemStr() + commit.summary
 		newLineCharCount = releaseNoteString.count("\n")
 		if releaseNoteString[-1] == "\n":
 			newLineCharCount = newLineCharCount - 1
 		releaseNoteString = releaseNoteString.replace("\n", "\n  ", newLineCharCount)
 		releaseNoteString += " (" + str(getChangeIdAOSPLink(commit.changeId))
 		for bug in commit.bugs:
 			releaseNoteString += ", " + str(getBuganizerLink(bug))
 		releaseNoteString += ")"
 		return self.getListItemStr() + releaseNoteString

 	def makeReleaseNotesSection(self, sectionCommitType):
 		sectionHeader = MarkdownBoldText(getTitleFromCommitType(sectionCommitType))
 		markdownStringSection = ""
 		for commit in self.commits:
 			if commit.changeType != sectionCommitType: continue
 			commitString = self.formatReleaseNoteString(commit)
 			if self.forceIncludeAllCommits or commit.releaseNote != "":
 				markdownStringSection = markdownStringSection + commitString
 				if markdownStringSection[-1] != '\n':
 					markdownStringSection += '\n'
 		markdownStringSection = "\n%s\n\n%s" % (sectionHeader, markdownStringSection)
 		return markdownStringSection

 	def __str__(self):
 		markdownString = ""
 		for commitType in CommitType:
 			markdownString += self.makeReleaseNotesSection(commitType)
 		return markdownString

 class GitilesDiffLogLink(MarkdownLink):
     def __str__(self):
         return "[%s](%s)" % (self.linkText, self.linkUrl)

 def getGitilesDiffLogLink(version, startSHA, endSHA, projectDir):
 	"""
 	@param startSHA the SHA at which to start the diff log (exclusive)
 	@param endSHA the last SHA to include in the diff log (inclusive)
 	@param projectDir the local directory of the project, in relation to frameworks/support

 	@return A [MarkdownLink] to the public Gitiles diff log
 	"""
 	baseGitilesUrl = "https://android.googlesource.com/platform/frameworks/support/+log/"
 	# The root project directory is already existent in the url path, so the directory here
 	# should be relative to frameworks/support/.
 	if ("frameworks/support" in projectDir):
 		print_e("Gitiles directory should be relative to frameworks/support; received incorrect directory: $projectDir")
 		exit(1)
 	if startSHA != "":
 		return GitilesDiffLogLink("Version %s contains these commits." % version, "%s%s..%s/%s" % (baseGitilesUrl, startSHA, endSHA, projectDir))
 	else:
 		return GitilesDiffLogLink("Version %s contains these commits." % version, "%s%s/%s" % (baseGitilesUrl, endSHA, projectDir))

 class LibraryHeader(MarkdownHeader):
 	"""
 	Markdown class for a Library Header in the format:

 	### Version <version> {:#<artifactIdTag-version>}

 	An artifactId tag is required because artifactIds may be can be grouped by version, in which case the tag is not obvious
 	"""
 	def __init__(self, groupId="", version="", artifactIdTag=""):
 		self.markdownType = HeaderType.H3
 		self.text = "%s Version %s {:#%s%s}" % (groupId, version, artifactIdTag, version)

 class ChannelSummaryItem:
 	"""Generates the summary list item in the channel.md pages, which take the format:

 		* [<Title> Version <version>](/jetpack/androidx/releases/<groupid>#<version>)

 		where <header> is usually the GroupId.
 	"""
 	def __init__(self, formattedTitle, groupId, version, artifactIdTag=""):
 		self.text = "* [%s Version %s](/jetpack/androidx/releases/%s#%s%s)\n" % (formattedTitle, version, groupId.lower(), artifactIdTag, version)

 	def __str__(self):
 		return self.text

 class LibraryReleaseNotes:
 	""" Structured release notes class, that connects all parts of the release notes.  Creates release
 	notes in the format:
 		<pre>
 		<[LibraryHeader]>
 		<Date>

 		`androidx.<groupId>:<artifactId>:<version>` is released. The commits included in this version
 		can be found <[MarkdownLink]>.

 		 <[CommitMarkdownList]>
 		</pre>
 	"""
 	def __init__(self, groupId, artifactIds, version, releaseDate, fromSHA, untilSHA, projectDir, requiresSameVersion, commitList=[], forceIncludeAllCommits=False):
 		"""
 		@property groupId Library GroupId.
 		@property artifactIds List of ArtifactIds included in these release notes.
 		@property version Version of the library, assuming all artifactIds have the same version.
 		@property releaseDate Date the release will go live.  Defaults to the current date.
 		@property fromSHA The oldest SHA to which to query for release notes.  It will be
 					excluded from release notes, but the next newer SHA will be included.
 		@property untilSHA The newest SHA to be included in the release notes.
 		@property projectDir The filepath relative to the parent directory of the .git directory.
 		@property requiresSameVersion True if the groupId of this module requires the same version for
 				  all artifactIds in the groupId.  When true, uses the GroupId for the release notes
 				  header.  When false, uses the list of artifactIds for the header.
 		@property commitList The initial list of Commits to include in these release notes.  Defaults to an
 				  empty list.  Users can always add more commits with [LibraryReleaseNotes.addCommit]
 		@param forceIncludeAllCommits Set to true to include all commits, both with and without a
 				 release note field in the commit message.  Defaults to false, which means only commits
 				 with a release note field are included in the release notes.
 		"""
 		self.groupId = groupId
 		self.artifactIds = artifactIds
 		self.version = version
 		self.releaseDate = MarkdownDate(releaseDate)
 		self.fromSHA = fromSHA
 		self.untilSHA = untilSHA
 		self.projectDir = projectDir
 		self.commitList = commitList
 		self.requiresSameVersion = requiresSameVersion
 		self.forceIncludeAllCommits = forceIncludeAllCommits
 		self.diffLogLink = MarkdownLink()
 		self.commits = commitList
 		self.commitMarkdownList = CommitMarkdownList(commitList, forceIncludeAllCommits)
 		self.summary = ""
 		self.bugsFixed = []
 		self.channelSummary = None

 		if version == "" or groupId == "":
 			raise RuntimeError("Tried to create Library Release Notes Header without setting " +
 					"the groupId or version!")
 		if requiresSameVersion:
 			formattedGroupId = groupId.replace("androidx.", "")
 			formattedGroupId = self.capitalizeTitle(formattedGroupId)
 			self.header = LibraryHeader(formattedGroupId, version)
 			self.channelSummary = ChannelSummaryItem(formattedGroupId, formattedGroupId, version)
 		else:
 			artifactIdTag = artifactIds[0] + "-" if len(artifactIds) == 1 else ""
 			formattedArtifactIds = (" ".join(artifactIds))
 			if len(artifactIds) > 3:
 				formattedArtifactIds = groupId.replace("androidx.", "")
 			formattedArtifactIds = self.capitalizeTitle(formattedArtifactIds)
 			self.header = LibraryHeader(formattedArtifactIds, version, artifactIdTag)
 			formattedGroupId = groupId.replace("androidx.", "")
 			self.channelSummary = ChannelSummaryItem(formattedArtifactIds, formattedGroupId, version, artifactIdTag)
 		self.diffLogLink = getGitilesDiffLogLink(version, fromSHA, untilSHA, projectDir)

 	def getFormattedReleaseSummary(self):
 		numberArtifacts = len(self.artifactIds)
 		for i in range(0, numberArtifacts):
 			currentArtifactId = self.artifactIds[i]
 			if numberArtifacts == 1:
 				self.summary = "`%s:%s:%s` is released. " % (self.groupId, currentArtifactId, self.version)
 			elif numberArtifacts == 2:
 				if i == 0: self.summary = "`%s:%s:%s` and " % (self.groupId, currentArtifactId, self.version)
 				if i == 1: self.summary += "`%s:%s:%s` are released. " % (self.groupId, currentArtifactId, self.version)
 			elif numberArtifacts == 3:
 				if (i < numberArtifacts - 1):
 					self.summary += "`%s:%s:%s`, " % (self.groupId, currentArtifactId, self.version)
 				else:
 					self.summary += "and `%s:%s:%s` are released. " % (self.groupId, currentArtifactId, self.version)
 			else:
 				commonArtifactIdSubstring = self.artifactIds[0].split('-')[0]
 				self.summary = "`%s:%s-*:%s` is released. " % (
 					self.groupId,
 					commonArtifactIdSubstring,
 					self.version
 				)
 		self.summary += "%s\n" % self.diffLogLink
 		return self.summary

 	def capitalizeTitle(self, artifactWord):
 		artifactWord = artifactWord.title()
 		keywords = ["Animated", "Animation", "Callback", "Compat", "Drawable", "File", "Layout",
 					"Pager", "Pane", "Parcelable", "Provider", "Refresh", "SQL", "State", "TV",
 					"Target", "View", "Inflater"]
 		for keyword in keywords:
 			artifactWord = artifactWord.replace(keyword.lower(), keyword)
 		return artifactWord

 	def addCommit(self, newCommit):
 		for bug in newCommit.bugs:
 			bugsFixed.append(bug)
 		commits.append(newCommit)
 		commitMarkdownList.add(newCommit)

 	def __str__(self):
 		return "%s\n%s\n\n%s%s" % (self.header, self.releaseDate, self.getFormattedReleaseSummary(), self.commitMarkdownList)
	#!/usr/bin/python3
	#
	# Copyright (C) 2020 The Android Open Source Project
	#
	# Licensed under the Apache License, Version 2.0 (the "License");
	# you may not use this file except in compliance with the License.
	# You may obtain a copy of the License at
	#
	# http://www.apache.org/licenses/LICENSE-2.0
	#
	# Unless required by applicable law or agreed to in writing, software
	# distributed under the License is distributed on an "AS IS" BASIS,
	# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	# See the License for the specific language governing permissions and
	# limitations under the License.
	#

	from ReleaseNoteMarkdown import *
	from GitClient import CommitType, getTitleFromCommitType, getChangeIdAOSPLink, getBuganizerLink

	class CommitMarkdownList:
	"""Generates the markdown list of commits with sections defined by enum [CommitType], in the format:

	New Features
	- <[Commit.summary]> <[getChangeIdAOSPLink]> <[getBuganizerLink] 1> <[getBuganizerLink] 2>...
	API Changes
	- <[Commit.summary]> <[getChangeIdAOSPLink]> <[getBuganizerLink] 1> <[getBuganizerLink] 2>...
	Bug Fixes
	- <[Commit.summary]> <[getChangeIdAOSPLink]> <[getBuganizerLink] 1> <[getBuganizerLink] 2>...
	External Contribution
	- <[Commit.summary]> <[getChangeIdAOSPLink]> <[getBuganizerLink] 1> <[getBuganizerLink] 2>...
	"""
	def __init__(self, commits=[], forceIncludeAllCommits=False):
	self.forceIncludeAllCommits = forceIncludeAllCommits
	self.commits = commits

	def add(self, commit):
	self.commits.append(commit)

	def getListItemStr(self):
	return "- "

	def formatReleaseNoteString(self, commit):
	if commit.releaseNote != "":
	releaseNoteString = commit.releaseNote
	else:
	releaseNoteString = self.getListItemStr() + commit.summary
	newLineCharCount = releaseNoteString.count("\n")
	if releaseNoteString[-1] == "\n":
	newLineCharCount = newLineCharCount - 1
	releaseNoteString = releaseNoteString.replace("\n", "\n ", newLineCharCount)
	releaseNoteString += " (" + str(getChangeIdAOSPLink(commit.changeId))
	for bug in commit.bugs:
	releaseNoteString += ", " + str(getBuganizerLink(bug))
	releaseNoteString += ")"
	return self.getListItemStr() + releaseNoteString

	def makeReleaseNotesSection(self, sectionCommitType):
	sectionHeader = MarkdownBoldText(getTitleFromCommitType(sectionCommitType))
	markdownStringSection = ""
	for commit in self.commits:
	if commit.changeType != sectionCommitType: continue
	commitString = self.formatReleaseNoteString(commit)
	if self.forceIncludeAllCommits or commit.releaseNote != "":
	markdownStringSection = markdownStringSection + commitString
	if markdownStringSection[-1] != '\n':
	markdownStringSection += '\n'
	markdownStringSection = "\n%s\n\n%s" % (sectionHeader, markdownStringSection)
	return markdownStringSection

	def __str__(self):
	markdownString = ""
	for commitType in CommitType:
	markdownString += self.makeReleaseNotesSection(commitType)
	return markdownString

	class GitilesDiffLogLink(MarkdownLink):
	def __str__(self):
	return "[%s](%s)" % (self.linkText, self.linkUrl)

	def getGitilesDiffLogLink(version, startSHA, endSHA, projectDir):
	"""
	@param startSHA the SHA at which to start the diff log (exclusive)
	@param endSHA the last SHA to include in the diff log (inclusive)
	@param projectDir the local directory of the project, in relation to frameworks/support

	@return A [MarkdownLink] to the public Gitiles diff log
	"""
	baseGitilesUrl = "https://android.googlesource.com/platform/frameworks/support/+log/"
	# The root project directory is already existent in the url path, so the directory here
	# should be relative to frameworks/support/.
	if ("frameworks/support" in projectDir):
	print_e("Gitiles directory should be relative to frameworks/support; received incorrect directory: $projectDir")
	exit(1)
	if startSHA != "":
	return GitilesDiffLogLink("Version %s contains these commits." % version, "%s%s..%s/%s" % (baseGitilesUrl, startSHA, endSHA, projectDir))
	else:
	return GitilesDiffLogLink("Version %s contains these commits." % version, "%s%s/%s" % (baseGitilesUrl, endSHA, projectDir))

	class LibraryHeader(MarkdownHeader):
	"""
	Markdown class for a Library Header in the format:

	### Version <version> {:#<artifactIdTag-version>}

	An artifactId tag is required because artifactIds may be can be grouped by version, in which case the tag is not obvious
	"""
	def __init__(self, groupId="", version="", artifactIdTag=""):
	self.markdownType = HeaderType.H3
	self.text = "%s Version %s {:#%s%s}" % (groupId, version, artifactIdTag, version)

	class ChannelSummaryItem:
	"""Generates the summary list item in the channel.md pages, which take the format:

	* [<Title> Version <version>](/jetpack/androidx/releases/<groupid>#<version>)

	where <header> is usually the GroupId.
	"""
	def __init__(self, formattedTitle, groupId, version, artifactIdTag=""):
	self.text = "* [%s Version %s](/jetpack/androidx/releases/%s#%s%s)\n" % (formattedTitle, version, groupId.lower(), artifactIdTag, version)

	def __str__(self):
	return self.text

	class LibraryReleaseNotes:
	""" Structured release notes class, that connects all parts of the release notes. Creates release
	notes in the format:
	<pre>
	<[LibraryHeader]>
	<Date>

	`androidx.<groupId>:<artifactId>:<version>` is released. The commits included in this version
	can be found <[MarkdownLink]>.

	<[CommitMarkdownList]>
	</pre>
	"""
	def __init__(self, groupId, artifactIds, version, releaseDate, fromSHA, untilSHA, projectDir, requiresSameVersion, commitList=[], forceIncludeAllCommits=False):
	"""
	@property groupId Library GroupId.
	@property artifactIds List of ArtifactIds included in these release notes.
	@property version Version of the library, assuming all artifactIds have the same version.
	@property releaseDate Date the release will go live. Defaults to the current date.
	@property fromSHA The oldest SHA to which to query for release notes. It will be
	excluded from release notes, but the next newer SHA will be included.
	@property untilSHA The newest SHA to be included in the release notes.
	@property projectDir The filepath relative to the parent directory of the .git directory.
	@property requiresSameVersion True if the groupId of this module requires the same version for
	all artifactIds in the groupId. When true, uses the GroupId for the release notes
	header. When false, uses the list of artifactIds for the header.
	@property commitList The initial list of Commits to include in these release notes. Defaults to an
	empty list. Users can always add more commits with [LibraryReleaseNotes.addCommit]
	@param forceIncludeAllCommits Set to true to include all commits, both with and without a
	release note field in the commit message. Defaults to false, which means only commits
	with a release note field are included in the release notes.
	"""
	self.groupId = groupId
	self.artifactIds = artifactIds
	self.version = version
	self.releaseDate = MarkdownDate(releaseDate)
	self.fromSHA = fromSHA
	self.untilSHA = untilSHA
	self.projectDir = projectDir
	self.commitList = commitList
	self.requiresSameVersion = requiresSameVersion
	self.forceIncludeAllCommits = forceIncludeAllCommits
	self.diffLogLink = MarkdownLink()
	self.commits = commitList
	self.commitMarkdownList = CommitMarkdownList(commitList, forceIncludeAllCommits)
	self.summary = ""
	self.bugsFixed = []
	self.channelSummary = None

	if version == "" or groupId == "":
	raise RuntimeError("Tried to create Library Release Notes Header without setting " +
	"the groupId or version!")
	if requiresSameVersion:
	formattedGroupId = groupId.replace("androidx.", "")
	formattedGroupId = self.capitalizeTitle(formattedGroupId)
	self.header = LibraryHeader(formattedGroupId, version)
	self.channelSummary = ChannelSummaryItem(formattedGroupId, formattedGroupId, version)
	else:
	artifactIdTag = artifactIds[0] + "-" if len(artifactIds) == 1 else ""
	formattedArtifactIds = (" ".join(artifactIds))
	if len(artifactIds) > 3:
	formattedArtifactIds = groupId.replace("androidx.", "")
	formattedArtifactIds = self.capitalizeTitle(formattedArtifactIds)
	self.header = LibraryHeader(formattedArtifactIds, version, artifactIdTag)
	formattedGroupId = groupId.replace("androidx.", "")
	self.channelSummary = ChannelSummaryItem(formattedArtifactIds, formattedGroupId, version, artifactIdTag)
	self.diffLogLink = getGitilesDiffLogLink(version, fromSHA, untilSHA, projectDir)

	def getFormattedReleaseSummary(self):
	numberArtifacts = len(self.artifactIds)
	for i in range(0, numberArtifacts):
	currentArtifactId = self.artifactIds[i]
	if numberArtifacts == 1:
	self.summary = "`%s:%s:%s` is released. " % (self.groupId, currentArtifactId, self.version)
	elif numberArtifacts == 2:
	if i == 0: self.summary = "`%s:%s:%s` and " % (self.groupId, currentArtifactId, self.version)
	if i == 1: self.summary += "`%s:%s:%s` are released. " % (self.groupId, currentArtifactId, self.version)
	elif numberArtifacts == 3:
	if (i < numberArtifacts - 1):
	self.summary += "`%s:%s:%s`, " % (self.groupId, currentArtifactId, self.version)
	else:
	self.summary += "and `%s:%s:%s` are released. " % (self.groupId, currentArtifactId, self.version)
	else:
	commonArtifactIdSubstring = self.artifactIds[0].split('-')[0]
	self.summary = "`%s:%s-*:%s` is released. " % (
	self.groupId,
	commonArtifactIdSubstring,
	self.version
	)
	self.summary += "%s\n" % self.diffLogLink
	return self.summary

	def capitalizeTitle(self, artifactWord):
	artifactWord = artifactWord.title()
	keywords = ["Animated", "Animation", "Callback", "Compat", "Drawable", "File", "Layout",
	"Pager", "Pane", "Parcelable", "Provider", "Refresh", "SQL", "State", "TV",
	"Target", "View", "Inflater"]
	for keyword in keywords:
	artifactWord = artifactWord.replace(keyword.lower(), keyword)
	return artifactWord

	def addCommit(self, newCommit):
	for bug in newCommit.bugs:
	bugsFixed.append(bug)
	commits.append(newCommit)
	commitMarkdownList.add(newCommit)

	def __str__(self):
	return "%s\n%s\n\n%s%s" % (self.header, self.releaseDate, self.getFormattedReleaseSummary(), self.commitMarkdownList)