[reporter] snippets and enhancements

stbischof commented 5 years ago

It would be nice if we could make the reporter more easy to configurate and to activate optional features.

Add a References subsection in the Component section to document component's references.
Add a set of configuration snippets in subsections describing the PIDs/FactoryPIDs of components which must be explicitly activated thanks to template parameters.
if the outputFile is readme.md and templateFile and templateDir is empty it should use the default one

now:


<plugin>
    <groupId>biz.aQute.bnd</groupId>
    <artifactId>bnd-reporter-maven-plugin</artifactId>
    <version>${bnd.version}</version>
    <configuration>
        <reports>
            <report>
                <outputFile>readme.md</outputFile>
                <templateFile>default:readme.twig</templateFile>
                <parameters>
                    <templateDir>default:</templateDir>
                </parameters>
            </report>
        </reports>
    </configuration>
</plugin>

target:


<plugin>
    <groupId>biz.aQute.bnd</groupId>
    <artifactId>bnd-reporter-maven-plugin</artifactId>
    <version>${bnd.version}</version>
    <configuration>
        <reports>
            <report>
                <outputFile>readme.md</outputFile>
                <parameters>
                    <md.extension.all>false</md.extension.all>
                    <md.extension.configadmin>true</md.extension.configadmin>
                    <md.extension.configurator>true</md.extension.configurator>
                    <md.extension.feature>true</md.extension.feature>
                    <md.extension.gogo>true</md.extension.gogo>
                    <md.extension.reference>true</md.extension.reference>
                </parameters>
            </report>
        </reports>
    </configuration>
</plugin>

@cdelg what do you think about? do you have some ideas for more snippets

cdelg commented 5 years ago

if the outputFile is readme.md and templateFile and templateDir is empty it should use the default one

If you want this, the outputFile should match readme.*\.md instead. First, in case of sub-bundles and also to generate a readme file from a Jar with Bnd CLI.

md.extension.*

Maybe they should be more specific (we can have more options in the future) and it will be easier if we can guess the Boolean type from the name. What about show.confsnippet.* ?

md.extension.feature

Is it in the OSGi spec? If not, the name should contain the kind of the feature, no?

md.extension.gogo

What do you expect from this?

md.extension.reference

Is it for the References section, maybe this one should not be an extension, just as any other sections currently in the template.

cdelg commented 5 years ago

Thinking a little more about simplify the usage to generate Readme files, we could also add a new Bnd CLI subcommand and a new maven mojo. A user could generate Readme files without configuring the workspace/projects : bnd.jar exportreport readme

stbischof commented 5 years ago

The new command/mojo sounds much better.

Gogo ( afaik it is not in spec) should be a list of gogo commands. It is just a filter on the component Prosperties osgi.command.scope and osgi.command.function to show all command the bundle offers

Features is sling features. But there is a draft for a osgi spec. https://github.com/osgi/design/blob/master/rfcs/rfc0241/rfc-0241-Features.pdf In chapter 5.4.1 is a json feature descriptor. It would nice to have snippets for the bundle and configuration section.

cdelg commented 5 years ago

I think we should have two PRs (maybe issues too), one for the added sub-command/mojo the other for the confsnippets.

For Gogo, if I understand well, you will not have additional information than the list of commands which is already available in the Properties section under the osgi.command.scope and osgi.command.function properties, not sure it will be really useful? However, we could add a new reporter plugin that will look for Gogo commands and add an entry into the report with the command description, the optional parameters, the default value etc.

stbischof commented 5 years ago

I agree with the 2 PR's

Your are right, that the Gogo commands are in the Property Section of an Component. But if you have a Bundle with multiple Components and Commands it could help to have one (optional) Commands Section in the Readme.

Should we use space or tab as indentation?

cdelg commented 5 years ago

Your are right, that the Gogo commands are in the Property Section of an Component. But if you have a Bundle with multiple Components and Commands it could help to have one (optional) Commands Section in the Readme.

In this case I am not sure that the template is the right place to put the logic, I think the template should be kept as simple as possible. We can create a plugin that collect all the Gogo commands of a bundle and add them to the report, the template will be easier to write and we can still improve the Gogo plugin in the future to attach additional information such as the description, etc.

Also, I am not sure if this one has to be optional since the reported information are directly derived from what the bundle contains, which we can oppose to the confsnippets where we have no clue on which configuration mechanism the user relies (configurator, Sling Feature, etc.). If we make the Gogo part optional, so why not every parts of the readme (licenses, developers,...). We can still consider this in the future, globally, if there is a use case where users wants to precisely control what should be reported in their readme.

Should we use space or tab as indentation?

I would say spaces.

Also, in Twig you can control whitespaces with - (eg; {%- myCommand -%}). But as our templates are bit complex (a lot of conditionals and loops), I have used the - in every control statements and added whitespace explicitly when needed (eg; {{ ' ' }} or {{ '\n' }}). It is then easier to not have trailing whitespaces when a condition is not satisfied.

cdelg commented 5 years ago

[x] Simplify configuration to generate readme files. (done in #3334).
[ ] Add a References subsection in the Component section to document component's references.
[ ] Add a set of configuration snippets in subsections describing the PIDs/FactoryPIDs of components which must be explicitly activated thanks to template parameters (those snippets could be formed in the template or with a plugin to be reusable in other use cases, @stbischof ?).
[ ] Add a Gogo plugin (to collect commands) and add a Gogo section to in the default readme template.
[x] Compact the sections Documentation, Source Repository, Artifact Repository into one Links section.

Links section example:

Links

Documentation
Source code (clone with scm:git:git@github.com:myxzcompagny/max-min.git)
Artifact repository

@stbischof, are you agree with this plan? Do you start working on it? Can you provide a PR for some of this tasks?

stbischof commented 5 years ago

I agree @cdelg

I can contribute some PR for:

reading all gogo infos into a dto #3336->#3338 ( but not the command )
references section #3338
some snippelts #3338

stbischof commented 5 years ago

@cdelg I merged everything into PR #3338. Could you please have a look and give me some feedback?

cdelg commented 5 years ago

@stbischof I will try before this week-end.

bjhargrave commented 4 years ago

Is this still ongoing work?

cdelg commented 4 years ago

Yes, I have local copy of @stbischof 's work, I will push a set of PRs soon.

bjhargrave commented 4 years ago

OK, we pushed this out of the next release (5.0). So no rush.

cdelg commented 4 years ago

thanks

rotty3000 commented 4 years ago

Note I think @bjhargrave meant 5.1 (since for 5.0 there is kind of a rush ;) )

bjhargrave commented 4 years ago

@cdelg @stbischof What is the status of this issue?

stbischof commented 4 years ago

@bjhargrave i will so some PR in the next days

features:

[x] gogo commands (PR: #3847 )
[x] improve bundle location (PR: #3916)
[x] reference bindings section (PR: #3920)
[x] OSGi-Configurator snippets (PR: #3920)
[ ] handle optional Template sections ( PR:#3924 ,follow here #3923)
[x] Checksum ( PR:#3927 )
[x] Try with Resource on Jar an Process (PR: #3918)

Could you have a look at the questions https://osgi.org/bugzilla/show_bug.cgi?id=234 I tried to create a feature-config-snippet from metatype. An Answer would help

bjhargrave commented 4 years ago

Could you have a look at the questions https://osgi.org/bugzilla/show_bug.cgi?id=234 I tried to create a feature-config-snippet from metatype. An Answer would help

You would be better to ask questions in the osgi-dev@mail.osgi.org mail list about the configurator spec. I personally did not work on that spec.

stbischof commented 4 years ago

@bjhargrave I think we could close this issue after merging PR #3924.

The only to-do is to decide which sections use which tags. Especially the default tag. See #3923

bjhargrave commented 4 years ago

OK, I will close this then. Thanks for all the work!

bndtools / bnd

[reporter] snippets and enhancements #3317

Links