Site reports having Changes linked with GitHub

[Tibor17]

My proposal is to have a Project Site for JUnit generated by every release/build.

This site (part of project webpage) will have project documentation as well as will include links to Issues/PullRequests for the particular Release on https://github.com/junit-team/junit/

The only thing the contributor has to do is to add a new line into changes.xml for his pull. The file will be located in the root of project. For instance the issue appears in changes.xml: <action dev="aramirez" type="fix" issue="800">Fix for release JUnit 4.12</action>

As far as I remember Stephen Connolly was working on Maven Site for the JUnit. This extends the site.

For more info, see the configuration in pom.xml and usage of changes.xml http://maven.apache.org/plugins/maven-changes-plugin/usage.html

[Tibor17]

@stephenc Did you have spare time to establish site generation on JUnit? As far as I remember you wanted other site layout. I would like to integrate a list of changes with links of JUnit issues based on changes.xml into the mvn site.

[stephenc]

the changes.xml route is tricky... from my experience using a manual tracking it's a pain... but if people are happy to follow that pain, that can work.

I'd like to use the markdown doxia renderer to let the majority of the hand-written site content be in markdown. The main page will likely need to be an XDOC as when you need to do slightly more fancy things, which a front page needs, then you need the XDOC style to control the content

[Tibor17]

@stephenc Is there another alternative for the Maven to generate these links of changes in site automatically? For instance based on label in a pull request or an issue.

[stephenc]

You can have it slurp the SCM changelog and expose that... but it is also less than ideal and you don't get issue links

[stephenc]

https://github.com/junit-team/junit/pull/787

[marcphilipp]

I think the current site along with the release notes is sufficient.

@Tibor17 What do you think?

[Tibor17]

Instead we should try generate changes.xml by the plugin:

      <reporting>
        <plugins>
          <plugin>
            <artifactId>maven-changes-plugin</artifactId>
            <version>2.11</version>
            <configuration>
              <!-- for GitHub-report -->
              <columnNames>Type,Priority,Key,Summary,Resolution</columnNames>
              <onlyCurrentVersion>true</onlyCurrentVersion>
              <resolutionIds>Fixed</resolutionIds>
              <sortColumnNames>type DESC,Priority DESC,Key</sortColumnNames>
              <maxEntries>1000</maxEntries>
              <skip>true</skip>
            </configuration>
            <reportSets>
              <reportSet>
                <reports>
                  <report>github-report</report>
                </reports>
              </reportSet>
            </reportSets>
          </plugin>
        </plugins>
      </reporting>

[kcooney]

@Tibor17 could you try generating release notea for 4.12 and show us what they would have looked like? Perhaps you could paste them in a google doc or as a page on the wiki

[Tibor17]

This is the result http://junit.czweb.org/site/github-report.html

You can see the issues without label 4.12 because you did not mark them. For instance this one was fixed in 4.12 but it wasn't marked with the label in PR 461: IncludeExcludeCategory should accept many categories + configurable

[kcooney]

@Tibor17 so "Fix Version" is obtained from the 'Milestone' set in the bug/pull, not from the git labels?

[Tibor17]

I mean milestone, but look at #461 in the list, it does not have any milestone specified. Therefore I have configured the plugin in order to see all issues with whatever milestone. This means if we want to select issues only by milestones, then the list is incomplete in 4.12. To make it complete you should not forget to set the milestone. So you have two options: a complete list or list per milestone. Just choose which you like more.

[kcooney]

We've been using "milestone" for planning purposes, but we don't usually set it when we merge pull requests, so I think we should not select issues by milestone, and not show "Fix version" since it is only accurate if we always set the milestone.

Other than that, I'd be fine trying out the maven-changes-plugin. Could you send us a pull?

[marcphilipp]

:hand: I have a veto here.

[marcphilipp]

We already had that plugin, I disabled it in b69b3ab15e0aa03fa8e95f43d897af29843fca1b.

[marcphilipp]

IMHO it does not add any information. Given the current frequency of our releases (two years) it will almost always show an outdated list of issues that are browsable (and up-to-date) on GitHub anyways. How does this list add any value to our website?

[kcooney]

@marcphilipp manually keeping the release notes up to date is a pain, and we've missed important commits in the release notes. I was hoping this plugin would allow us to automate the process of putting together the release notes.

aside: we all need to be better at our commit messages. b69b3ab doesn't state why the plugins was disabled. having good commit messages would be necessary IMHO to do any kind of automation of the release notes (unless there is some easy way to go from commit to pull request that I'm not aware of)

[marcphilipp]

I agree that my commit message in b69b3ab does not state the intent of the commit. The corresponding pull request description however does: #1010.

It should be possible through git to find all merged pull requests. In addition, we would have to find commits not from pull requests.

However, I believe generating the release notes from the git log or GitHub issues is utopian. IMHO the only thing that will definitely help is to ship more often.

[stephenc]

Yes I agree that it is a utopian ideal.

For my day job, we have a separate database backed tool that displays the release notes for each version. The database is seeded from the commit log, but then hand edited to produce the final release notes.

Perhaps the thing to do is use the changes.xml based changelog report and have a script to seed the changes.xml from the git log?

[kcooney]

@marcphilipp How did you find the corresponding pull for that commit?

I'm expecting that we would need to hand-edit any generated release notes. But we know we've missed important pull requests in the release notes, so I don't like the idea of having the release notes generated entirely by hand. We'll miss things, and it's yet another thing to do with my limited time I can spend on JUnit.

If there are existing tools out there to generate a changes.xml from the git log, I'm fine doing that. But I wouldn't want us to write new scripts.

Related: one of the benefits of using the hub tool is that we can change the commit message when we merge to main, without changing who the author of the change is. If we do that, then it'll be much easier to produce useful release notes, because the commit message should summarize what was done.

[Tibor17]

I don't agree that hand-editing report is nowadays cool process in whatever s/w development. The PRs might be outdated but commit numbers won't be. So you can extend the list with additional column referring to commit (see .git/info/refs) by hacking the HTML. Perhaps there would be a way to hack the plugin with a new feature which would guess that the particular PR belongs to certain ${project.version} according to the closing date & commit done. Anyway the apache projects use this plugin, so I am wondering that you don't. Imaging that you are a user of JUnit and you want to see what was fixed - obviously you go to this list and you don't need to see the code changes.