Details
-
Type:
New Feature
-
Status: Closed (View Workflow)
-
Priority:
Major
-
Resolution: Done
-
Affects Version/s: None
-
Fix Version/s: None
-
Labels:
-
Story Points:4
-
Epic Link:
-
Sprint:Fall 2019 Sprint 1, Fall 2019 Sprint 2, Fall 2019 Sprint 3
Description
David Norris wrote a simple maven plugin called "bundle markdown encoder," currently released in our legacy maven repository called "repo3".
The "bundle markdown encoder" translates a file called "README.md" in a project's root directory into base64-encoding and writes the output to the bundle-description field in the resulting MANIFEST file. To see how this looks, download any of the IGB App jar files from their Bitbucket repos and look at their MANIFEST files. (Recall that an OSGi bundle is nothing but a jar file with some extra meta-data adde to the MANIFEST.)
This base64-encoding of the README.md file enables App Store and also IGB itself to display the README.md file to users. In App Store the README.md appears on an App's page, where developers can log in and edit it. (Once an App is deployed on App Store, the App Store "takes over" responsibility for maintaining the README.md.) In IGB, the README.md appears in the App Manager GUI when a user selects the App. Both App Store and App Manager GUI can read and render markdown properly.
However, sometimes we want to use this top-level README.md as a way to communicate to developers, not users. This is because bitbucket and github both display this top-level README.md file to users when they visit the home page for a git repository. Normally, this README file gets used to explain to developers how they can contribute to a project. Users probably don't want to see this.
Solution:
- Let's modify the plugin so that a developer can specify the markdown file they want to base64-encoded.
Also, write up a detailed testing strategy so that testers who may not be super-familiar with maven can check that your code is working as expected. This will include explaining to them how to run your new plugin without it being deployed publicly. For example, they could build it on their local and run mvn install to copy it to their local .m2 maven repository. And of course, for this to work, you have to increment the version.
Bitbucket repository for the base 64 markdown encoder plugin:
Attachments
Activity
For the next steps, please add instructions on how to use the plugin to its README.md file in bitbucket, including example configurations you described above.
Prof. [~aloraine], README.md file changes can be seen at:
https://bitbucket.org/pkulka10/bundlemarkdownencoder_prutha/src/IGBF-1949/README.md
Submitting the ticket for first level review.
Thanks.
Requests:
- Please include markdown file tags in example text for POM and indicate that README.md at top-level of the project is used if markdownFile tag is absent.
- Check how the README.md looks in a browser when user visits bitbucket. Check that XML is getting rendered properly.
Prof. [~aloraine], the XML is getting rendered properly.
Also, Moved the text which was mentioned in the "NOTE" to top of the file and included markdown file tags in the exmaple text for POM which was already present in the file.
https://bitbucket.org/pkulka10/bundlemarkdownencoder_prutha/src/IGBF-1949/
Please let me know if thats correct.
Prof. [~aloraine], I have submitted pull request for the same.
The code changes are present at https://bitbucket.org/lorainelab/bundlemarkdownencoder/pull-requests/1/igbf-1949/diff
Could you please merge it into bundle markdown encoder plugin master?
Thanks.
Merged. The instructions added are very clear. See "Super Simple IGB App" for another example. Moving this to "Closed."
Prof. [~aloraine], I have checked the bundle markdown encoder plugin code.
The person who was previously working on it has already given a provision for user-specified file as input. The parameter is already in use and if not specified, it sets the default value to README.md file.
We just need to specify the name of the markdown file which we want to use like this in the "bundle-markdown-encoder" plugin tag of the "pom.xml" under "executions>execution" tag of the plugin wherever it is used:
<configuration>
<markdownFile>TESTMarkDown.md</markdownFile>
</configuration>
for example:
<plugin>
<groupId>org.lorainelab</groupId>
<artifactId>bundle-markdown-encoder</artifactId>
<version>1.0.0</version>
<executions>
<execution>
<goals>
<goal>encodeMarkdown</goal>
</goals>
<configuration>
<markdownFile>TESTMarkDown.md</markdownFile>
</configuration>
</execution>
</executions>
</plugin>
We don't need to change anything in the plugin as it is working fine.
Also, found this useful link on how to create a maven bundle plugin from scratch:
https://maven.apache.org/guides/plugin/guide-java-plugin-development.html
Please let me know if there is anything else which I can do related to the same ticket.