6.5 KiB

Raw Permalink Blame History

Contributing to ITSERR HORTUS

Field	Value
Project	ITSERR HORTUS
Document	Repository Contributing Guide
Version	1.0
Status	Proposed
Last updated	2026-03-05

Thank you for contributing to ITSERR HORTUS.

HORTUS is a web-based research platform for Religious Studies that combines catalog and content management, collaboration tools, user profiles, support services, training, events, news, expert discovery, metadata workflows, and interoperability with external scholarly services.

We welcome improvements to code, documentation, tests, accessibility, integrations, metadata schemas, workflows, examples, tutorials, and issue triage.

Before You Start

Search first. Check existing issues, pull requests, and documentation before opening a new item.
Use the right channel.
- Functional bugs, enhancements, and documentation updates belong in the repository issue tracker or the HORTUS support workflow.
- Security vulnerabilities must not be reported publicly. Follow SECURITY_HORTUS.md.
Discuss larger changes early. For changes that affect architecture, metadata models, authentication, integrations, or user-facing workflows, open an issue first so the direction can be agreed before implementation.

Ways to Contribute

You can contribute by:

reporting bugs with reproducible steps;
proposing enhancements or UX improvements;
improving accessibility, clarity, translations, and documentation;
contributing tests or test fixtures;
submitting code changes;
improving examples, templates, or configuration guidance;
helping review issues, pull requests, and documentation.

Code of Conduct

All participation in this repository is governed by CODE_OF_CONDUCT_HORTUS.md.

Reporting Bugs and Requesting Enhancements

When opening an issue, include:

a short descriptive title;
the affected feature or workflow;
steps to reproduce or validate;
expected result and actual result;
screenshots, logs, or sample payloads when useful;
environment details (browser, OS, version, commit, branch, deployment context);
impact and urgency.

For user-facing platform problems in a hosted HORTUS environment, use the HORTUS Support / Issues path when that is the operationally correct channel.

Contribution Workflow

1. Prepare the change

fork the repository or create a feature branch, depending on the project workflow, you can also refer the local setup guide;
use a focused branch for one logical change;
keep changes small and reviewable whenever possible.

2. Implement carefully

Please follow these baseline expectations:

respect the coding style and linting rules already configured in the repository;
use clear commit messages;
add or update tests for behavioral changes;
update documentation when behavior, setup, UI, APIs, or workflows change;
do not commit secrets, credentials, tokens, private data, or generated artefacts that should not be versioned.

3. Consider HORTUS-specific quality requirements

Contributions should preserve or improve:

security and privacy: especially for authentication, authorization, profile data, exports, uploads, document parsing, and external integrations;
open-science and metadata quality: especially when touching DOI, ORCID, Zenodo, Zotero, or metadata mapping behavior;
accessibility: user-facing changes should consider responsive behavior and WCAG-oriented usability;
documentation quality: user-facing changes should be reflected in relevant guides, FAQs, release notes, or support material;
testability: new behavior should be traceable to an issue, use case, or user story.

4. Submit a pull request

Your pull request should:

link to the relevant issue or explain the context clearly;
describe what changed and why;
identify any migration, configuration, or deployment implications;
mention any documentation updates included or still required;
include screenshots or recordings for UI changes;
call out accessibility, security, or data-model impact where relevant.

Pull Request Checklist

Before requesting review, confirm that you have:

kept the scope focused;
run the relevant tests and checks;
resolved linting and static-analysis issues that apply to your changes;
updated documentation where needed;
added screenshots for UI changes;
considered accessibility and responsive behavior for user-facing changes;
avoided committing secrets or personal data;
described any security, privacy, API, metadata, or integration impact;
linked the change to an issue, task, or user story.

Review Expectations

Maintainers may request changes before merge. In general, a contribution should not be merged until:

the pull request is understandable and reviewable;
required checks pass;
relevant documentation is updated;
any blocking review comments are resolved.

Documentation Contributions

Documentation is a first-class contribution. This includes:

README content;
setup and deployment notes;
release notes or changelog entries;
user guides, FAQs, and troubleshooting content;
developer notes and examples;
support and operational guidance relevant to the repository.

Write clearly, prefer plain language, and keep instructions testable.

Technology-Specific Notes

HORTUS may include multiple technologies. When contributing:

for frontend work, follow the repository's UI, linting, and accessibility conventions;
for backend work, follow the repository's API, logging, and test conventions;
for integration work, document contract changes and edge cases;
for infrastructure or automation work, document environment variables and deployment assumptions;
for Python utilities, follow the repository's Python style and test rules;
for Java or Spring-based modules, follow the repository's formatting and documentation conventions.
for code management workflow and standards to be followed please refere the guide here

Licensing

By contributing, you agree that your contribution may be distributed under the repository's open-source license.

SECURITY_HORTUS.md
CODE_OF_CONDUCT_HORTUS.md

Change Log

Version	Date	Summary
1.0	2026-03-05	Initial HORTUS-specific contributing guide aligned to RS015-derived repository needs.

6.5 KiB Raw Permalink Blame History