Documentation: Provide guidance on where to ask GlassFish related Questions

[ahfarag]

Environment Details

• GlassFish Version (and build number): 7.0.10
• JDK version: openjdk version "21.0.1" 2023-10-17
• OS: Ubuntu
• Database: NA

---

Problem Description

Many users may be unsure about where to ask questions or seek help regarding GlassFish-related queries. Clear guidance on the website can enhance the user experience and foster a more supportive community.

Steps to reproduce

• Look at https://glassfish.org/
• I don't see any good suggestion for where to ask questions.

Impact of Issue

It will benefit the community especially, beginners.

[OndroMih]

You are right, this should be improved on the website, thank you for your feedback.

Meanwhile, the best places to ask questions, are:

• GlassFish mailing list: https://accounts.eclipse.org/mailing-list/glassfish-dev
• The #glassfish channel in the Jakarta EE Slack (Info how to connect to it here: https://jakarta.ee/connect/)
• Stavkoverflow, using the [glassfish] tag: https://stackoverflow.com/questions/tagged/glassfish

If you have trouble getting answers, you can also contact our OmniFish team directly and ask us anything about GlassFish: https://omnifish.ee/contact-us/

[merks]

You might consider enabling discussions on the GitHub repository. It’s a bit nicer than a mailing list I think. Just a thought…

[hantsy]

I would like enabling Discussions, nowadays in my circle a lot of younger developers have not used maillist at all.

[hantsy]

@OndroMih I would like add wizard based template to the New Issue button, check the Github docs: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#configuring-the-template-chooser

• Bug Report
• New Feature/Improvement
• Idea/Proposal
• Question
  • GlassFish mailing list: https://accounts.eclipse.org/mailing-list/glassfish-dev
  • The #glassfish channel in the Jakarta EE Slack (Info how to connect to it here: https://jakarta.ee/connect/)
  • Stavkoverflow, using the [glassfish] tag: https://stackoverflow.com/questions/tagged/glassfish
• Professional Support
  • If you have trouble getting answers, you can also contact our OmniFish team directly and ask us anything about GlassFish: https://omnifish.ee/contact-us/

[escay]

I have the same questions but mainly based on building / developing glassfish code.
Some feedback / observations I have made in the last two weeks, not meant as critic, but maybe some input for new issues to improve upon.

I looked at the slack channel but the #glassfish channel is not visible by default on the left side. You need to search for #glassfish in the top bar, select the channel there and then join the channel. You cannot read the channel without joining. Joining is a bit of a threshold holding me back since I do not know what was discussed in the past.

I looked at the glassfish-dev mailing list, but it contains mainly release notes, it did not invite me to ask questions.
The discussions option in github would be nice, I like how it works at https://github.com/orgs/primefaces/discussions

Stackoverflow was not considered by me, I would not expect dev related questions on stackoverflow.

Some basic glassfish development questions I have are:

How to checkout code?

I would expect it on the github page in detail, but it is located at the website, I found it via
https://glassfish.org/documentation.html
-> select Get Involved (https://glassfish.org/CONTRIBUTING.html)
-> select Pull Request Acceptance Workflow (https://glassfish.org/pr_workflow)
and a day later I had trouble finding it again when starting on github.

The pr_workflow documentation is good, I managed to send in a pull request using the documentation.

What are the style guides?

• Checkstyle configuration is located at qa/src/main/resources/org/glassfish/qa/config/checkstyle/checkstyle.xml
• Page https://glassfish.org/CONTRIBUTING.html mentions:

Information regarding source code management, builds, coding standards, and more: https://projects.eclipse.org/projects/ee4j.glassfish/developer

however I could not find coding standards.

Which formatting is used for new code?

• I saw one of the issues mention an IntelliJ and Eclipse formatter configuration: https://github.com/eclipse-ee4j/ee4j/tree/master/codestyle

Which IDEs are commonly used to develop Glassfish and how are they efficiently configured?
I had some problems setting up Eclipse IDE, tips are welcome, I have a number of detail questions here.
Things like: m2e usage, Windows experience, memory settings for maven, for the IDE (eclipse.ini), having all 400 modules open or not etc.

What are the best ways to build the code.
There are 4 ways defined at https://github.com/eclipse-ee4j/glassfish which is an excellent start👌
Some additional information is welcome, plus de '1.5 minute' does not resemble my laptop performance ;)
Unluckily I ran into some dependency issue which required me to use the -Pstaging option on my very first builds. Perhaps it should be part of the 4 main options as a fifth option.

What is the main module structure?
It would also be useful to known a bit of the module structure. For now I can look around in the pom files and profiles to get an idea. Still not sure after two weeks looking a bit around what nucleus means, nucleus versus appserver, I see hk2, /docs is clear.

[arjantijms]

@escay thanks for the elaborate feedback. Many of those things are good to make clear indeed.

Specially the formatting is the EE4J formatting as defined here: https://github.com/eclipse-ee4j/ee4j/tree/master/codestyle

Every EE4J project should adhere to it, but of course in practice and with all the history that does not always happen.

Still not sure after two weeks looking a bit around what nucleus means, nucleus versus appserver,

This should be good to be documented in the packages as well. As we inherited the code base too, it's a question how useful these two really are today. I think they were brought into existence when Sun wanted to chase all the current hypes of each year. nucleus was the more universal "kernel" of the system, able to support the Ruby on Rails server, the Groovy Server, the PHP server and whatever was popular back then, while appserver was the Java EE implementation build on top of the kernel and shipped by default.

Since we only focus on building and supporting Jakarta EE, I'm not sure we need this distinction really.

JBoss EAP has something similar with "WildFly" and "WildFly core": https://github.com/wildfly I'm not sure where they use it for either.

[arjantijms]

As a small update, explicit code conventions were added here:

https://github.com/eclipse-ee4j/glassfish/blob/master/CODE_CONVENTIONS.md

These were taken from the Eclipse EE4J wiki, which got lost when the wiki and files moved to GitHub.

[escay]

Some other development questions I have:

What is the preferred way of committing multiple fixes / creating pull requests for an issue?
Example: I am looking into a complex issue and want to:

• document existing code
• refactor existing code without making the real fix for the issue (move some constructor logic / remove unused code / ..)
• add unit tests for existing code
• make a fix, or maybe make 2 or 3 fixes

Ideally I commit these as separate items, for easier code review and better commit descriptions.
How can I achieve this? Should I create new issues? Should I create '3' branches and '3' pull requests for the same issue?
Or should it just be 1 big pull request? How do I make clear the pull request is not the final fix yet, but is only a general improvement eventually leading up to a fix? Any best practices guideline is appreciated.

Is draft usage supported?
Do you use / support drafts in this project?
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request
Is there a way to ask for a 'draft' to be reviewed, or should I just create a pull request and wait for the review?
Could draft usage be documented, similar like pull requests steps are documented?

Ask for help while investigating an issue
Is there a way to ask other developers for their opinion on existing code? For example when investigating an issue.
Via a comment? via a pull request? In my case I would like to know if some active developers have knowledge of specific Glassfish modules, but I do not want to address anyone out of the blue. A discussion forum might help here?

TODO statements
I read somewhere, I believe in the checkstyle, that TODO statements should not be added in the code. How should I make notes of code where I think improvements could be made? Should I make a new issue. Or add a TODO and handle it as part of a pull request discussion?

Issue closing procedure
What is the general procedure to close issues in this project? Closing once a pull request is accepted? Or waiting for the reporter to close it?

Unit test guidelines
A short list of items like this could be useful:

• naming convention of class and methods, perhaps easiest to point to an existing example like "com.sun.enterprise.resource.pool.PoolSizeTest" or "com.sun.enterprise.resource.pool.datastructure.RWLockDataStructureTest" for one with Mocks and hamcrest usage.
• assertion framework preferences?
  • org.hamcrest:hamcrest is being used / available for assertThat test, and is available via nucleus parent pom (https://hamcrest.org/)
• mocking preferences? Pure java classes to override methods versus Mocking?
  • org.easymock:easymock is being used, and is available via nucleus parent pom (https://easymock.org/)
  • org.jmockit:jmockit is being used, and is available via nucleus parent pom (https://jmockit.github.io/)
  • wiremock-maven-plugin is used in tcl tests (https://github.com/ipastusi/wiremock-maven-plugin/releases -> new group id since 8.0)

[dmatej]

Some other development questions I have:

What is the preferred way of committing multiple fixes / creating pull requests for an issue? Example: I am looking into a complex issue and want to:

• document existing code
• refactor existing code without making the real fix for the issue (move some constructor logic / remove unused code / ..)
• add unit tests for existing code
• make a fix, or maybe make 2 or 3 fixes

Ideally I commit these as separate items, for easier code review and better commit descriptions. How can I achieve this? Should I create new issues? Should I create '3' branches and '3' pull requests for the same issue? Or should it just be 1 big pull request? How do I make clear the pull request is not the final fix yet, but is only a general improvement eventually leading up to a fix? Any best practices guideline is appreciated.

Simply said, we are all people and any help is welcome. You can create an issue if you have something to elaborate in it, or document the whole process. Other people can read, give you some advices, discuss an issue, whatever. Creating an issue is not mandatory, one can create a PR without any issue, but sometimes it is better if you want "signal" that you are already working on something and other people should wait, or the opposite that you have found something broken and someone else should fix it.

The issue I have with "best practices for every project" is that nobody reads them. Many people even did not read the README on the welcome page of this repository. So we mostly do the opposite - if somebody does some bad step, we will get him on track.

GlassFish project is also a huge piece of software, so there are always questions if I should do this or that - and it has also some evolution, so what was not possible/good three years ago, is now alright. The project sources also are not absolutely consistent, we are slowly working on that, but there is a lot of freedom. The mandatory requirement is that every change should go in the right direction.

Is draft usage supported? Do you use / support drafts in this project? https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request Is there a way to ask for a 'draft' to be reviewed, or should I just create a pull request and wait for the review? Could draft usage be documented, similar like pull requests steps are documented?

YES. Draft is allowed and it is a good thing to

• Let Jenkins to verify the current state. (note: I am not sure if it starts automatically for non-committers too, probably not)
• Let others to check from time to time if you are going in the right direction or if you need a help or something.

Ask for help while investigating an issue Is there a way to ask other developers for their opinion on existing code? For example when investigating an issue. Via a comment? via a pull request? In my case I would like to know if some active developers have knowledge of specific Glassfish modules, but I do not want to address anyone out of the blue. A discussion forum might help here?

We enabled discussions recently, but you can also ask in the issue. Sometimes it takes some time until somebody answers, you can imagine why, all reasons possible :-)

TODO statements I read somewhere, I believe in the checkstyle, that TODO statements should not be added in the code. How should I make notes of code where I think improvements could be made? Should I make a new issue. Or add a TODO and handle it as part of a pull request discussion?

• TODO statements are not forbidden here, but they are an antipattern, because now you can still find 20 years old TODOs in the code. But it is still better than pretending that the work is done and correct.

Issue closing procedure What is the general procedure to close issues in this project? Closing once a pull request is accepted? Or waiting for the reporter to close it?

It depends, when you use * Fixes #1234567890 on the first line, GitHub automatically closes the issue after PR is merged. Otherwise we can do it manually OR we will not do that when you write to the PR that it is just a part of the work.

Unit test guidelines A short list of items like this could be useful:

• naming convention of class and methods, perhaps easiest to point to an existing example like "com.sun.enterprise.resource.pool.PoolSizeTest" or "com.sun.enterprise.resource.pool.datastructure.RWLockDataStructureTest" for one with Mocks and hamcrest usage.

We use absolutely standard naming of tests. *Test for unit test (doesn't matter if with mocks) and *ITest or *IT (better) for integration tests (tests allocating ports so it could go into a conflict with other test; depends on operating system; slow test; ...).

• assertion framework preferences?

  • org.hamcrest:hamcrest is being used / available for assertThat test, and is available via nucleus parent pom (https://hamcrest.org/)

• mocking preferences? Pure java classes to override methods versus Mocking?

  • org.easymock:easymock is being used, and is available via nucleus parent pom (https://easymock.org/)
  • org.jmockit:jmockit is being used, and is available via nucleus parent pom (https://jmockit.github.io/)
  • wiremock-maven-plugin is used in tcl tests (https://github.com/ipastusi/wiremock-maven-plugin/releases -> new group id since 8.0)

EasyMock is preferred. But generally is recommended to use what is already used in the module (or project). Here it is EasyMock. There were (or are?) some JMockit tests too, I'm not sure now.