next step in the generic documentation - after some additional work, starting now there is a capability to track changes in all community components.
Example
Live example on Real Date - SCN Design Studio Community -> select "Change Log".
How Does it Work?
Form the technical perspective - the same tool which is generating the technical documentation is also tracking changes between such generation for:
- component properties in contribution.xml
- new property introduced
- property changed
- property deleted (this should never happen actually)
- component ZTL methods in contribution.ztl
- method inserted
- method properties changed
- method implementation changed
- component /res folder content
- /def content changed
- /spec folder changed
- /*js files changed (rendering part)
The changes are noted in a file called "state.properties" in sdkhelp repository. Example here for Real Date.
to those who want to understand this technically.. all changes are noted there, also MD5 for content of the component files. Once something change, the delta is calculated and stored to second JSON file:
Then, again the properties file gets new content and is ready for next change.
Idea Behind
as written last week in Community SDK - Call for Help in Documentation, the only way to go forward is a help from you - users of the components.
Therefore, I try to fill in the new repository "sdkhelp" with content, here the change log.
This state.json file is requested when the HTML page is loading and the change log is build with UI5 "TimeLine" component.
Every component has now a folder in the SDK Help repository where the dynamic part of the documentation pages can be edited by contributors. here the path on the RealDate examples to "changes" folder.
sdkhelp/web/components/utils/realdate/changes
Structure of "a change"
keep in mind, that this is generated, so the initial structure is quite technical, but - every one can update it (you can ask for access to the sdkhelp repo if you can and want help on this).
state.property - PROPERTY file
changelog.json - JSON file
The change contains
{
// author: free text, default is "n/a", but can be changed of course - indicates who made the change
"author": "Karol",
// changes: currently not directly evaluated, here is the technical information what has been changed...
"changes": [
{
"change": "Resource def - contribution.ztl",
"status": "untested"
},
{
"change": "Ztl Function getDayName",
"status": "untested"
},
{
"change": "Ztl Function getMonthName",
"status": "untested"
}
],
// date: when the change has been made, simple notation
"date": "2015-4-7",
// filterValue: some value for the filter, can be "fix" | "extension" | "improvement" | or some other. This is visible in the TimeLine for filtering
"filterValue": "fix",
// icon: an icon which appears in the timeline, I use flag for fix, note for other changes, better ideas are welcome.
"icon": "sap-icon://flag",
// test-*: now the most interesting part... test-* properties - here a comment, status and test icon can be placed. this will indicate in the log if this change is validated by someone.
"test-comment": "both methods are now returning string",
"test-icon": "sap-icon://accept",
"test-status": "ok",
// text:initially it is generated by the tool, but can be changed manually by the person who makes the change. the generated content lists the content from the "changes" area
"text": "Changes: Resource def - contribution.ztl;Ztl Function getDayName;Ztl Function getMonthName;",
// shorter title which is displayed on top of any change
"title": "There were 3 changes in the component. Changing return type for getMonthName() and getDayName()"
},
In Short
This will allow tracking of changes on component level, and with some more code also creation of any release log, but for this I had no time.
Next Steps... (coming soon)
with similar structure I think we can proceed also with the other pages, blogs, examples and introduction - the content structure will be specified, every one can add it by direct check in into the sdkhelp repository.
Free Participation
So, anyone who wants to participate, let us know that you want to be inserted into contributors, just comment on the issue:
Please add Me to Contributors in SDK Help Repository
Steps-by-Step (how to become a test - collaborator)
1. request collaborator permissions on this page - Please add Me to Contributors in SDK Help Repository
prerequisite - you need to have a user in github, so you need to register first.
2. Choose component and its change you want to retest, list here - Component List - SCN Design Studio Community
(now you are a community collaborator)
3. find the corresponding change file in the repository - e.g. here is RealDate file: Real Date - sdkhelp/state.json
4. see which change is not yet retested - this is manifested with the line:
"test-status": "untested",
(build a tests scenario for this change - ideally in local mode to share with others)
5. when you can confirm that this change is ok, edit the corresponding properties test-* in this block (between { and }).
Edit can be done online in the repository (small button on right side 'Edit'), so you do not have to use eclipse or other tools.
e.g.
BEFORE it was as here:
"test-comment": "not tested yet",
"test-icon": "sap-icon://note",
"test-status": "untested",
"text": "calculation for month name adjusted - one index was incorrect.",
"title": "getMonthName() returned incorrect month"
AFTER test:
"test-comment": "Month name returns correct value now in English, see also example named 'Test for getMonthName'",
"test-icon": "sap-icon://accept",
"test-status": "passed",
"text": "calculation for month name adjusted - one index was incorrect.",
"title": "getMonthName() returned incorrect month"
(optionally, only if you have a scenario which you can share)
6a. attach example in the "examples.json" which is one folder above in the structure (some documentation is directly in this file, blog will follow)
6b. you can also place a blog on this test if you think the change was big enough to be valuable to write about. then you can extend the file "blogs.json" also folder above.
Then, you can freely edit those files - and help others.
Documentation for changelog file.
Area for the person who has made the change.
// author:
the author, n/a initially, the developer can add his name
// date:
the date when the chnage was made (generated)
// title:
change title, initially generated but can be adjusted (probably by the developer)
// text:
a longer text, initially it is listing all areas of the change, can be also adjusted (probably by the developer)
// filterValue:
helps on filtering, should be one of
// bug | enhancement | improvement
// Try to be in sync with issues under https://github.com/org-scn-design-studio-community/sdkpackage/issues
// icon:
should correspond to the filterValue, should be one of
// flag | badge | bookmark
Area for the person who makes retest.
// test-comment:
any comment on the test scenario, you can also refer to some blog or others
// test-status:
the status, initially it is set to untested - this results in "yellow". change to:
// good or ok: when test is positive (small case)
// bad: when the test is negative (small case)
//
// test-icon:
icon corresponding to the status, change for
// flag - when status is bad
// accept - when status is good
- SAP Managed Tags:
