Contributing¶

To efficiently address our users' needs, we carefully designed our contributing guidelines and optimized our issue templates to ensure a great overall experience with our project.

Our goal is to ensure that our documentation, as well as our issue tracker, are well-structured, easy to navigate, and searchable, so you can find what you need quickly and efficiently. Thus, when you follow our contribution guidelines, we can help you much faster.

In this section, we guide you through our processes.

Checklist¶

Before interacting within the project, please take a moment to consider the following questions. By doing so, you ensure that you use the correct issue template and provide all necessary information when interacting with our community.

Before creating an issue¶

• Are you using the appropriate issue template, or is there another one that better fits the context of your request?

• Have you checked if a similar bug report or change request has already been created, or have you stumbled upon something that might be related?

• Did you fill out every field as requested, and did you provide all additional information we maintainers need to comprehend your request?

Before commenting¶

• Is your comment relevant to the topic of the current issue, or is it a better idea to create a new issue, as it's not or only loosely related?

• Does your comment add value to the conversation? Is it constructive and respectful to our community and us maintainers? Could you just use a reaction instead?

Licensing of contributions¶

By sharing code within the Zensical ecosystem – including in our Discord channel, issue tracker, and Zensical Spark – you agree to license your contributions under the MIT license. Please note that contributions are your own and do not fall under Zensical’s jurisdiction; we cannot be held liable for any issues arising from contributed code.

Incomplete contributions¶

We have carefully designed our contribution process to ensure that issues on our issue tracker can be reviewed and addressed efficiently. Each field in our issue templates is thoughtfully structured to capture the essential details needed to fully understand your concern.

Therefore, we require all requested information to be provided in full.

The checklist at the end of each template is a tool to help you verify that you've included everything necessary – it should not be marked off unless each point has been fully addressed. This ensures that every user and maintainer, regardless of experience, can properly assess the content and severity of an issue.

Filling an issue takes time and effort. Before opening one, please use the search function to avoid any duplicates and ensure your time is well spent. Your cooperation is crucial in keeping all Zensical platforms constructive and organized.

We reserve the right to handle issues that do not adhere to our guidelines as follows:

Incomplete issues¶

We reserve the right to close issues lacking essential information, such as missing minimal reproductions or those not adhering to the quality standards and requirements specified in our issue templates.

We'll reopen an issue once the missing information has been provided.

Questions as issues¶

We reserve the right to close questions opened as any kind of issue. The issue tracker is not a place for questions, but rather for detailed bug reports, documentation issues, and change requests that adhere to the quality standards laid out in this guide.

Questions can be asked in our Discord channel or within Zensical Spark.

Duplicated issues¶

To maintain organized and efficient communication within our issue tracker, we reserve the right to close any duplicated issues. Opening multiple channels to report the same issue hinders our ability to effectively manage and address community concerns. This approach is vital for efficient time management, as duplicates can consume the time of multiple team members simultaneously. Ensuring that each issue or discussion is unique and progresses with new information helps us to maintain focus and support our community.

Reopened issues¶

We further reserve the right to immediately close issues that are reopened without providing new information or simply because users have not yet received a response to their issue/question, as the issue is marked as incomplete.

Generated issues¶

While we believe in the value and efficiency that automated tools bring to identifying potential issues (such as those identified by Lighthouse, Accessibility tools, and others), simply submitting an issue generated by these tools does not constitute a complete bug report.

These tools sometimes produce verbose outputs and may include false positives, which necessitate a critical evaluation. You are, of course, welcome to attach generated reports to your issue. However, this does not substitute the requirement for a minimal reproduction or a thorough discussion of the findings.

We reserve the right to mark these issues as incomplete and close them. This practice ensures that we are addressing genuine concerns with precision and clarity, rather than automated outputs.