Adding Java to TA language nav

[meghan-kradolfer]

We now have a golden path for setting up Java repos, so we should update the docs to allow customers to easily find the documentation on setup.

At the moment a customers have to go to References -> Importing JUnit XML. It would be easier for them just to see Java in the languages and then link to this page.

[buildkite-docs-bot]

Preview URL: https://2714--bk-docs-preview.netlify.app

[meghan-kradolfer]

Note: Because the new page goes to the same page as 'Importing JUnit XML' both nav items are highlighted. Is this ok? Or is better to create seperate views?

[KatieWright26]

Note: Because the new page goes to the same page as 'Importing JUnit XML' both nav items are highlighted. Is this ok? Or is better to create seperate views?

It does seem a bit weird / the duo highlighting might be unclear as to why we're doing that. I feel like people would raise it as a bug. Does the highlighting work similarly to the _nav.html.erb where you can pass a param action to signify which nav element to highlight?

[pda]

Interesting re. the nav highlighting.

It gets me thinking: nav highlighting aside, would people find it odd/sneaky/something that multiple nav items go to a single page which is more generic than some of those nav items suggest?

I guess the ideal thing would be adding a new Java-specific page which gives some guidance on how to get JUnit XML reports out of their Java test suite, and then links to the general Importing JUnit XML page.

[meghan-kradolfer]

Does the highlighting work similarly to the _nav.html.erb where you can pass a param action to signify which nav element to highlight?

Nope, the nav items are added through a yaml file. So the highlighting is done programming based of the url/path

[meghan-kradolfer]

It gets me thinking: nav highlighting aside, would people find it odd/sneaky/something that multiple nav items go to a single page which is more generic than some of those nav items suggest?

I guess the ideal thing would be adding a new Java-specific page which gives some guidance on how to get JUnit XML reports out of their Java test suite, and then links to the general Importing JUnit XML page.

What if we remove the 'Importing JUnit XML' nav and just have that under Java instead? It sounds like we only import JUnit XML so people would be looking for languages - Java anyway?

[pda]

What if we remove the 'Importing JUnit XML' nav and just have that under Java instead? It sounds like we only import JUnit XML so people would be looking for languages - Java anyway?

I don't think so, because JUnit XML is the common format emitted by multiple non-Java languages.
e.g. a Rust test runner: https://nexte.st/book/junit.html

[meghan-kradolfer]

What if we remove the 'Importing JUnit XML' nav and just have that under Java instead? It sounds like we only import JUnit XML so people would be looking for languages - Java anyway?

I don't think so, because JUnit XML is the common format emitted by multiple non-Java languages. e.g. a Rust test runner: https://nexte.st/book/junit.html

Ohh right, good to know! Hmm, maybe the best option is adding a new Java specific page. @gchan keen to get your reckons on this as well?

[gchan]

@meghan-kradolfer Yep, I agree with creating Java-specific page to get around the double highlighting in the nav.

I went through setting up a Java Junit test suite and documented my process

I got a little stuck on finding where the XML files are created so having some guidance on a new Java page on where to retrieve them and how to configure the plugin would be ideal.

For example, when using the Maven Surefire Plugin the files are generated in ${basedir}/target/surefire-reports/TEST-*.xml by default. So I configured the plugin like so

 - test-collector#v1.10.1:
     files: "target/surefire-reports/TEST-*.xml"
     format: "junit"

https://github.com/buildkite/ta-ingestion/blob/e4556f3a30682f044ecc17ff64d3eb1dbb8da22b/.buildkite/pipeline.yaml#L30C1-L32C26

[gilesgas]

It might be worthwhile considering implementing a redirect, similar to when you click on the Clusters > Queue metrics nav item in the Pipelines area of the docs and it redirects you to the Cluster queue metrics page of the docs.

That way, you can avoid the odd multiple-page highlighting issue you described above.

Take a look at how this is implemented in the source code and let me know if you need help.

I hope to document some more best practices on how to contribute to the Buildlkite Docs at some point in the near future, when time permits.

[meghan-kradolfer]

Thanks @gilesgas! @pda and @gchan how do you feel about this PR being just to set up that redirect, so then it solves the initial issue of Java language not being immediately findable?

I think if we are adding a whole new set of instructions for Java then we may also need to do this in the suite setup page in TA and I can write a couple of extra tickets to do that

[niceking]

not a biggie but it would be nice to align the to: on this line and the line previous!

[gilesgas]

Just had a quick chat with @meghan-kradolfer and will approve this now (to unblock merging).
However, please feel free to seek approval from another colleague before merging this.

[niceking]

Nice! ✨ Just the one style comment but not a blocker to merging

[pda]

how do you feel about this PR being just to set up that redirect, so then it solves the initial issue of Java language not being immediately findable?

Good pragmatic step in the right direction; maintain momentum 💪🏼