RefPack Contribution Guide

Introduction

RefPack aims to be a community-driven standard and ecosystem. Your contributions, whether big or small, play a crucial role in its growth and improvement. By contributing, you help make reference data more accessible, reliable, and easier to use for everyone.

The RefStor project, which includes this gallery, the API, and core RefPack handling, is open source. You can find the main repository here: https://github.com/coretravis/RefStor.

The RefPack specification itself might be managed in the same repository or a dedicated one (e.g., https://github.com/coretravis/RefPackSpec). Please check the main project README for specifics on where to contribute to the spec.

Ways to Contribute

There are many ways you can contribute:

Reporting Bugs

If you find a bug in the RefPack CLI, this gallery website, the API, or any related tool, please report it by opening an issue on the relevant GitHub repository.

When reporting a bug, please include:

• A clear and descriptive title.
• Steps to reproduce the bug.
• What you expected to happen.
• What actually happened (including error messages or screenshots if applicable).
• Your environment (e.g., OS, browser version, CLI version).

Suggesting Enhancements

Have an idea for a new feature or an improvement to an existing one? We'd love to hear it! Please open an issue on GitHub, describing your suggestion:

• What is the problem you're trying to solve or the improvement you're envisioning?
• How would this enhancement benefit users?
• Any specific ideas on how it could be implemented (optional).

Code Contributions

If you're a developer, you can contribute directly to the codebase. This could involve fixing bugs, implementing new features, or improving performance.

1. Fork the relevant repository (e.g., RefStor).
2. Create a new branch for your feature or bugfix (git checkout -b feature/your-feature-name).
3. Make your changes, ensuring you adhere to existing coding styles and add tests where appropriate.
4. Commit your changes with clear and descriptive commit messages.
5. Push your branch to your fork (git push origin feature/your-feature-name).
6. Open a Pull Request (PR) against the main branch of the original repository.

Please see the Development Setup and Pull Request Process sections below for more details.

Documentation Improvements

Good documentation is key! If you find areas in the documentation (like this guide, the specification, or API docs) that are unclear, incorrect, or could be improved, please let us know by opening an issue or, even better, submitting a PR with your suggested changes.

Documentation files are typically written in Markdown.

Submitting Datasets

One of the most valuable contributions is submitting new, high-quality RefPack datasets to this registry!

1. Ensure your dataset is useful, from a reliable source, and properly licensed for distribution.
2. Package your dataset according to the RefPack Specification. Pay close attention to the data.meta.json manifest details, including clear authorship, licensing (SPDX identifier preferred), and descriptive tags.
3. Sign your manifest if you have a key management setup. If not, the registry might have options for unsigned community packages or guidance on how to proceed.
4. Validate your package using the RefPack CLI: refpack validate --package your-package.refpack.zip.
5. Use the Upload Package page on this site to submit your dataset.

Submitted datasets may undergo a review process before being publicly listed to ensure quality and adherence to community guidelines.

Code of Conduct

We are committed to providing a friendly, safe, and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristic. Please review our Code of Conduct (link usually found in the GitHub repository, e.g., CODE_OF_CONDUCT.md) before participating.

Development Setup (RefStor Example)

To contribute to the RefStor platform (this gallery, API, etc.):

1. Ensure you have the .NET SDK installed (currently targeting .NET 9, as per the solution overview).
2. Clone the repository: git clone https://github.com/coretravis/RefStor
3. Navigate to the solution directory: cd RefStor
4. Build the solution: dotnet build
5. To run the gallery: cd src/RefStor.Gallery then dotnet run.
6. Specific projects might have their own README files with more detailed setup instructions.

Pull Request Process

1. Ensure any install or build dependencies are removed before the end of the layer when doing a build.
2. Update the README.md or other relevant documentation with details of changes to the interface, this includes new environment variables, exposed ports, useful file locations and container parameters.
3. Increase the version numbers in any examples and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is SemVer.
4. Your PR will be reviewed by maintainers. You may be asked to make changes before it can be merged. We appreciate your patience and collaboration during this process.

Questions?

If you have questions about contributing, the RefPack format, or the RefStor platform, feel free to:

• Open an issue on the GitHub repository.
• Join any community channels linked in the project's main README (e.g., Slack, Gitter, Discord).