Contributing to the Ruby CFF Library¶ ↑

Introduction¶ ↑

Thank you for considering a contribution to the Ruby CFF Library!

If you intended to contribute to another part of the Citation File Format project, for example the Citation File Format specification itself, please contribute to the respective repository ({list of repositories in the citation-file-format GitHub organization}[https://github.com/orgs/citation-file-format/repositories]).

Please follow these guidelines. Their purpose is to make both contributing and accepting contributions easier for all parties involved.

There are many ways to contribute, e.g.:

• Tell a friend or colleague about the Citation File Format and Ruby CFF, or tweet about it

• Write blog posts, tutorials, etc. about the Citation File Format and Ruby CFF

• Review the format and its schema and documentation

• Improve wording in any prose output, including the specifications

• Create a new, better version of the schema and specifications

• Improve automated tests, continuous integration, documentation, etc.

Ground Rules¶ ↑

Your contribution to Ruby CFF is valued, and it should be an enjoyable experience. To ensure this there is the Ruby CFF Code of Conduct which you are required to follow.

Please always start any contribution that will change the contents of this repository from an issue. This may mean creating a new issue if it’s something that hasn’t been requested so far. This way,

• you can make sure that you don’t invest your valuable time in something that may not be merged; and

• we can make sure that your contribution is something that will improve Ruby CFF, is in scope, and aligns with the roadmap for the Ruby CFF and the Citation File Format.

Your First Contribution¶ ↑

If you are unsure where to begin with your contribution to CFF, have a look at the open issues in this repository, and see if you can identify one that you would like to work on.

If you have never contributed to an open source project, you may find this tutorial helpful: How to Contribute to an Open Source Project on GitHub.

Getting started¶ ↑

This is the workflow for contributions to this repository:

1. Take note of the code of conduct

2. Create a new issue if needs be, and discuss the changes you want to make with the maintainers and community

3. Fork the repository

4. Create a branch in your fork of the repository

5. Make changes in the new branch in your fork

6. Please don’t forget tests!

7. If you add any classes, modules, methods, attributes, or constants, please document them

8. Create a pull request

9. Address any comments that come up during review

10. If and when your pull request has been merged, you can delete your branch (or the whole forked repository)

This workflow is loosely based on GitHub flow, and you can find more information in the GitHub flow documentation.

Working with tests and documentation¶ ↑

There is a comprehensive test suite for Ruby CFF, which also contains a collection of test CITATION.cff files - both valid and invalid. Please add tests (and new test CITATION.cff files if appropriate) for any new features you add, or bugs you squash. It is advised to run these tests locally on your computer prior to submitting a pull request. However, if that’s not possible, you still can submit the pull request and later check the status of the tests for your pull request on GitHub.

To run the tests, assuming that you have all the dependencies installed, simply run:

$ rake

To rebuild the documentation, if you have added to it or changed it:

$ rake rdoc

Then load html/index.html into a Web browser and double check it.

FAQ¶ ↑

• These guidelines do not address aspect XYZ! What should I do now?

Please submit an issue, asking for clarification of and/or an addition to the guidelines.