I’ be interested in using template to see if it helps gathering more information. However, we should keep in mind that the nature of the issues may vary greatly in Apache Baremaps. For instance, we may have styling issues in the basemap (in which case we need coordinates, a screenshot and browser information) or bugs in codecs (in which case we’d prefer to have a problematic file that allows us to reproduce the issue, a command, or a test case).
We could start with a high-level template asking for as many information as possible and see where it takes us. E.g.: - Description - Environment - Steps to reproduce - Attachments (data and screenshots) Additionally, we should keep in mind that some feature requests don’t necessarily need to be implemented. For instance, #334 was created a long time ago and can be addressed by starting another jvm process for another tileset. Until now, I assume nobody needed it urgently enough to implement it. Perhaps we should close these issues and leave a comment so the author can push for it again if it is really necessary. This approach would allow us to keep the issue tracker in a cleaner state and to have a clearer roadmap (where we want the project to go). What do you think? Regarding the diagrams, Mermaid is a good option on GitHub. We used it for the data module, and it is welcome for documenting other parts of the project. The main challenge is likely keeping them up to date as the project evolves. https://github.com/apache/incubator-baremaps/tree/main/baremaps-data Best, Bertil > On 27 Jan 2025, at 00:19, Yongjun Hong <dev.yongj...@gmail.com> wrote: > > Additionally, leveraging PlantUML to visualize the dependencies and > interactions between the modules in Baremaps could be a great way to provide > clarity. > For example, we could draw like JUnit 5: > https://github.com/junit-team/junit5/blob/main/documentation/src/plantuml/component-diagram.puml > > I’d appreciate your feedback on my ideas. > > Best regards, > > Yongjun > > > >> >> Of course! >> >> Since I have contributed significantly to the JUnit5 framework, I am most >> familiar with that project. That’s why I often refer to it in my examples. >> >> 1. Issue Labeling >> >> In JUnit5, issues are automatically labeled based on their type when they >> are created. >> For example, a feature request issue is labeled as “type: new feature.” >> Additionally, a “status: new” label is applied using GitHub Actions. >> This allows newcomers reviewing the issue list to immediately understand >> that the issue is a feature request and is newly created. >> Furthermore, there are labels like “status: team discussion” for issues >> requiring internal discussion and “status: blocked” for issues that cannot >> proceed. These labels help users quickly grasp the current state of the >> issue. >> >> I believe it would be helpful if baremaps could also have automatic labeling >> based on the type of issue. While project maintainers can manually label >> issues, labeling itself can be a form of overhead. >> Adding a few essential labels to reflect the project’s current status would >> be beneficial. In my opinion, labels like “status: team discussion,” >> “status: blocked,” and “status: in progress” are essential. Other labels can >> be discussed and added as needed. >> >> 2. Issue Templates >> >> https://github.com/apache/incubator-baremaps/issues/334 >> >> Like this issue, I noticed that many issues in baremaps are described in a >> single line. While a single line can be sufficient for conveying >> information, I think having a structured template could make the process >> more efficient. Given the nature of the project, providing screenshots or >> logs might be critical for bug-related issues. Therefore, I suggest creating >> an issue template that outlines what information users should provide when >> submitting feature requests or reporting bugs. >> >> If there’s interest in adding a template, I can create an issue and submit a >> PR for it. >> >> 3, 4, 5 >> >> Currently, I don’t have concrete plans for points 3, 4, and 5. I plan to >> discuss further with Bertil and develop specific plans afterward. >> >> Thank you! >> >> Best regards, >> >> Yongjun >> >> github/yongjun: https://github.com/YongGoose >> >> >> >>> >>> Hi Yongjun, >>> >>> Thank you for sharing these suggestions from the perspective of a new >>> contributor. >>> Could you describe the specific changes you’d like to make? >>> We truly appreciate your contributions:) >>> >>> On Sun, Jan 26, 2025 at 12:20 PM 홍용준 <dev.yongj...@gmail.com >>> <mailto:dev.yongj...@gmail.com>> wrote: >>> >>> > Dear Baremaps Team, >>> > When I first explore an open-source project, I follow a series of steps to >>> > familiarize myself with it. Based on this experience, I have outlined a >>> > few >>> > suggestions that could enhance the onboarding experience for new >>> > contributors to the Baremaps project. >>> > >>> > 1. >>> > >>> > *Issue Labeling* >>> > >>> > While browsing the issues, I noticed that recent issues in the Baremaps >>> > project lack labels. Categorizing or prioritizing issues with labels >>> > can >>> > help new contributors quickly understand the context and navigate >>> > through >>> > them. >>> > 2. >>> > >>> > *Standardized Templates* >>> > >>> > Introducing a detailed and standardized issue template could make the >>> > project more approachable for contributors. For reference, JUnit5 >>> > provides >>> > well-structured issue templates that might serve as a good example: >>> > JUnit5 Issue Templates >>> > <https://github.com/junit-team/junit5/tree/main/.github/ISSUE_TEMPLATE> >>> > >>> > Similarly, a pull request (PR) template with a checklist could guide >>> > contributors before submitting their PRs. This would allow them to >>> > verify >>> > key requirements before maintainers review their submissions. For >>> > reference: >>> > JUnit5 Pull Request Template >>> > < >>> > https://github.com/junit-team/junit5/blob/main/.github/PULL_REQUEST_TEMPLATE.md >>> > > >>> > 3. >>> > >>> > *Ideal Issue Management Practices* >>> > >>> > Implementing an automated process to tag issues with labels like >>> > “waiting-for-triage” upon creation could make the issue-triage workflow >>> > smoother. Once maintainers review and categorize the issues, >>> > contributors >>> > can easily identify the type of issue and engage more effectively. >>> > 4. >>> > >>> > *Improved Documentation* >>> > >>> > The existing Getting Started guide is well-written. However, adding >>> > step-by-step instructions, similar to Apache Kafka’s quickstart guide >>> > <https://kafka.apache.org/quickstart>, could further enhance its >>> > usability. >>> > Alternatively, adopting a dual-track structure like TensorFlow's >>> > documentation, which caters separately to beginners and advanced users, >>> > might also be worth considering: >>> > TensorFlow Tutorials <https://www.tensorflow.org/tutorials> >>> > 5. >>> > >>> > *Comprehensive User Guide* >>> > >>> > While creating a comprehensive user guide may feel resource-intensive, >>> > it can significantly improve the experience for new users. For >>> > instance, >>> > JUnit provides an excellent User Guide >>> > < >>> > https://github.com/junit-team/junit5/tree/main/documentation/src/docs/asciidoc/user-guide >>> > > >>> > that >>> > serves as a long-term resource for contributors and users alike. >>> > >>> > I understand that some of these suggestions may require considerable time >>> > and effort to implement. However, they could be considered as part of >>> > long-term goals to make Baremaps even more accessible to the community. >>> > Finally, I would like to express my admiration for the incredible work >>> > behind Baremaps. I am looking forward to contributing consistently to this >>> > fantastic project. >>> > >>> > Best regards, >>> > >>> > Yongjun Hong >>> > >>> >>> >>> -- >>> Best wishes！ >>> CalvinKirs
