Thank you for your interest in contributing to Quire! No matter what level of experience you have, we welcome all contributions, big and small.
Developed by Getty, Quire is a digital publishing tool that can create dynamic publications in a variety of formats, including web, print, and e-book. Quire is an ideal tool for publishing beautiful, scholarly digital books optimized for visual imagery and designed to ensure publication content is widely accessible and stable.
Quire is open-source and free to use. View Quire's 3-clause BSD open source license. Please note: Quire v1 is currently in a pre-release phase. Testing and improvements are ongoing.
At the moment, the primary ways to contribute to Quire are reporting and fixing bugs or writing and improving the documentation. In time we will expand this to include suggesting features and enhancements. Please read the following guidelines carefully. Our goal is to make the process as effective and transparent as possible and to ensure that your contributions become part of Quire. Thank you for taking the time.
🗣CALLING ALL FIRST-TIMERS! — We can’t stress enough that Quire is open to contributors at all levels. That could mean making a modest fix, like correcting a typo in the docs, to a more intensive contribution, like fixing broken code. Here are a few resources especially for you:
- Find “good first issues” tagged in our issue tracker for the main
thegetty/quirerepo - Find “good first issues” tagged in our issue tracker for the
thegetty/quire-docsrepo - Read the Quire guide to Making Your First Contribution — in progress
- Learn more about contributing to open source at First Timers Only
Quire Core Team:
Greg Albers (@geealbers), product manager
David Newbury (@workergnome), product manager
Matthew Hrudka (@mphstudios), lead maintainer
Erin Cecele Dunigan (@Erin-Cecele), community manager
Contact us at quire@getty.edu
All are welcome. As an open-source community, Quire is committed to providing a safe, welcoming, transparent, and inclusive environment for all our community members and those wishing to become involved. Please see our Code of Conduct for more on the expectations and protections for our community members.
There are three main code repositories for Quire hosted on GitHub.
- quire: Quire’s primary repository, with the command-line interface and 11ty template packages
- quire-starter-default: The default starter content for a Quire project
- quire-docs: The Quire website and documentation.
In order to post or comment on an issue or submit contributions, you will first need to create a GitHub account.
We manage Quire through GitHub. If you are new to GitHub, we recommend starting with GitHub Docs. We also encourage you to check out Coding Train’s fantastic video series Git and Github for Poets. GitHub can be accessed through the command line or GitHub Desktop.
The first step to any contribution is to post a new issue or comment on an existing issue via our issue tracker. Be sure to briefly describe your proposed solution and say whether you may need help with any aspect of it. This approach has several advantages:
- Lets people know you’re working on it
- Gives the core team and the community a chance to give feedback before you do any work
- Helps to ensure your contribution will be accepted and successfully merged in
The second step to any contribution, once you’ve identified what you’d like to contribute, is to start work on it and eventually prepare to submit it. Read our submission guide below.
If you encounter what you believe is a reproducible bug while working on a Quire project and have confirmed that it has yet to be reported on our issue tracker, please complete the bug report form.
You will need to include the following information in your report:
- Description
- Expected behavior
- Actual behavior
- Steps to reproduce
- Quire and Node version numbers
- Operating system and web browser numbers
- Optional Terminal/Shell output, supporting info, screenshots, workarounds, etc.
Your bug report will then be reviewed by the core team to determine if it will be selected for development, backlogged, or closed.
Review our Bug Reporting Instructions
Check the issue tracker before posting your issue
Complete the bug report form
Post your thoughts/questions on our GitHub Discussions board if you are unsure
If you encounter a bug on our issue tracker that you would like to work on, take these two steps before getting started:
- Comment on the issue to let people know you are working on it
- Share your proposed solution so the core team and community can provide feedback or assistance
Follow the guidelines below to submit your contribution.
The Quire documentation and website are hosted in a separate quire-docs repository. The documentation is continuously being updated for clarity and completeness, but it’s not always easy to keep up with the pace of Quire’s development!
If there’s a section that you think is missing or could be improved, we’d love your help. And the documentation is itself a Quire site (built with v0), so it should be somewhat familiar to work in.
Find an existing issue to work on
Propose a new section or edit
Read the Quire Documentation Style Guide
The Quire community is global, and we hope to be able to continue to expand access to Quire, including to non-English speakers. Though we haven’t yet done any translation work on any of the documentation or materials, if that’s something you’re interested in doing, we’d love to talk to you.
Volunteer to do some translation
We’re always interested in adding step-by-step guides on creating popular customizations to the Resources section of our website. Maybe you have some tips on modifying shortcodes or styling in CSS in the custom.css. Chances are, the community would love to read about it.
Coming Soon...
Once you’ve identified your contribution on our GitHub issue tracker, you’ll next work on it and prepare to submit it to us for review as a pull request. A pull request says, “Hey, I did something useful for you, want to pull it in and merge it into your project?”
A pull request is a chance for Quire’s core team to evaluate the proposed changes made and decide whether to:
- merge them in as is
- merge them in with changes
- reject them
To avoid changes being rejected, we recommend you post about proposed changes on our issues board before you start work and also submit the pull request while work is still in progress.
A pull request doesn’t have to represent finished work. We always recommend opening a pull request early on, so others can watch or give feedback on your progress. Just mark it as a “WIP” (Work in Progress) in the subject line. As you make new commits to that branch and push them to GitHub, they’ll automatically be added to the open pull request.
This is something like what the development process may look like for you:
- Fork the repository and clone it locally.
- Learn more about forks and clones in GitHub’s docs on “Contributing and collaborating using GitHub Desktop”
- Create a branch and make your changes.
- Contribute in the style of the project to the best of your abilities. We’re going to be writing Quire’s Style Guides to help with this, but in the meantime, please try to follow the patterns you see in the existing pages, for instance, in naming classes, structuring page templates, and commenting your code for technical contributions, or in heading structure, tone, and tense for documentation contributions.
- Test your changes by running
npm installfollowed byquire preview. Depending on the changes you’ve made, you may also need to runquire build,quire pdf, andquire epubto make sure your changes worked. You may need to check various mobile views as well, which you can do using responsive design mode in your browser. In general, your goal with testing is to make sure your changes don’t break Quire’s existing styles or functionality. Of course, the project’s core team will be doing this, too, and can help guide you if something’s not working as expected.
- Submit a pull request through GitHub.
- If this is your first time putting in a pull request on a project like this, we recommend the First Contributions command line, or GitHub Desktop tutorial. Or, Kent C. Dodds' video series, “How to Contribute to an Open Source Project on GitHub”
- Reference any relevant issues or supporting documentation in your pull request description (for example, “Closes #203.”)
- Explain what the changes do and what your approach was. If there were alternate ways of doing it, mention them and tell us why you didn’t choose them.
- If this is a Work in Progress pull request, comment on where you are and what your next steps are.
- Include screenshots of the before and after if your changes include differences in HTML/CSS. Drag and drop the images into the body of your pull request as needed.
- Respond as needed to the review of your work by Quire’s core team.
- Answer questions in the pull request comments.
- Make changes and new commits if needed, or suggest alternate solutions if you have them.
- See your work merged into Quire! 🎉
Learn more in the Open Source Guide’s “How to Contribute to Open Source”.
At this point, we hope you feel ready to contribute! But don’t hesitate to ask for help or clarification. Everyone’s a beginner at first. And thank you again for your interest in making Quire a better tool for all! 🦄