Contributing to Libraries.io
Thanks for considering contributing. These guidelines outline how to contribute to the Libraries.io project.
Table of Contents
- Reporting bugs
- Suggesting enhancements
- Suggesting a new feature
- Your first contribution
- Tackling something meatier
What’s Libraries.io About?
Our goal is to raise the quality of all software.
By outlining our mission and strategy we hope to give you more power to make decisions and determine how best to spend your time. Specifically we tackle three distinct problems:
- Discovery: Helping developers make faster, more informed decisions about the software that they use.
- Maintainability: Helping maintainers understand more about the software they depend upon and the consumers of their software.
- Sustainability: Supporting undervalued software by highlighting shortfalls in contribution and funneling support to them.
Who is Libraries.io For?
Libraries.io currently caters for the needs of three distinct user groups:
- Google: is hungry for your linked datas so she can serve you up search traffic
- Searcher: is a developer with a problem, she is looking for something to help solve it.
- Maintainer: has a project that is used within and/or incorporates open dependencies. She needs to ensure her project(s) are working as expected for users.
These groups have been expanded into personas for contributors to reference.
What Should I Know Before I Get Started?
Code of Conduct
Libraries.io is an open and inclusive community of people working together. We expect contributors to abide by our contributor code of conduct which basically say ‘be excellent to each other’. Please report unacceptable behavior to firstname.lastname@example.org
We communicate predominately in English. Contributions to the project should be made with English as the first language. We are happy for members of the community to communicate in a language other than English in chat, email and video but be aware that this might be considered exclusive by other members of the community.
Documentation for the project as a whole is available at docs.libraries.io. These pages are generated from the documentation repo. Documentation that needs to be in every repo is replicated in required-files (currently limited to GitHub templates). Otherwise documentation will be specific to that repo. For example the main Libraries.io
README.md contains information about installing and running the main rails application.
If you wish to make contributions to Libraries.io then you’ll need a local version of the site to test. You can find instructions to install the correct Ruby version, Postgres, and to set up the database in our README.
How Can I Contribute?
The simplest thing that you can do to help us is by filing good bug reports, so here we go:
Before Submitting a Bug Report
- Double-check that the bug is persistent. The site is still in it’s infancy and sometimes artifacts may appear and disappear.
- Double-check the bug hasn’t already been reported on our issue tracker, they should be labelled
If something hasn’t been raised, you can go ahead and create a new issue using the template. If you’d like to help investigate further or fix the bug just mention it in your issue and check out our workflow.
The next simplest thing you can do to help us is by telling us how we can improve the features we already support, here we go:
Before Submitting an Enhancement
- Check that the enhancement is not already in our issue tracker, they should be labelled ‘enhancement’.
If there isn’t already an issue for feature then go ahead and create a new issue for it using the template. If you’d like to work on the enhancement then just mention it in a comment and check out our workflow.
Suggesting New Features
If you’re into this zone then you need to understand a little more about what we’re trying to achieve:
Before Suggesting a Feature
- Check that it aligns with our strategy and is specifically not in line with something we have said we will not do (for the moment this is anything to do with ranking people).
- Check that the feature is not already in our issue tracker, they should be tagged ‘feature’.
- Specifically check that it is not already a funded commitment.
If you’re still thinking about that killer feature that no one else is thinking about then please create an issue for it using the template.
Your First Contribution
You’re in luck! We label issues that are ideal for first time contributors with
first-pr. For someone who wants something a little more meaty you might find an issue that needs some assistance with
help wanted. Next you’ll want to read our workflow.
Tackling Something Meatier
Tickets are labeled by size, skills required and to indicate workflow. Details can be found in our labelling policy.
- Our strategy which outlines what our goals are, how we are going to achieve those goals and what we are specifically going to avoid.
- An overview of the components that make up the Libraries.io project and run the https://libraries.io site.
How Can I Talk To Other Contributors?
We try to use the following channels accordingly:
#generalchannel is used for general, water cooler-type conversation, contributor updates and issue discussion.
#eventsis used to share and discuss events that may be of interest to or attended by members of the community
#activitycontains notifications from the various platforms that we use to keep the Libraries.io project turning. Including notifications from GitHub, Twitter and our servers.
Members are encouraged to openly discuss their work, their lives, share views and ask for help using chat. It should be considered a safe space in which there is no such thing as a stupid question. Conversely no one contributor should ever be expected to have read something said in a chat. If someone should know something then it should be written down as an issue and/or documented in an obvious place for others to find.
Contributors are encouraged to share what they’re working on. We do this through daily or weekly updates in the
#general channel on Slack. Updates should take the format ‘currently working on X, expecting to move onto Y, blocked on Z’ where x, y and z are issues in our issue tracker.
Additionally we host an open hangout for any contributor to join at 5pm BST/GMT on a Tuesday to discuss their work, the next week’s priorities and to ask questions of other contributors regarding any aspect of the project. Again this is considered a safe space in which there is no such thing as a stupid question.
We have an account on Twitter at @librariesio. This is predominately used to retweet news, events and musings by contributors rather than as a direct method of communication. Contributors are encouraged to use @librariesio in a tweet when talking about the project, so that we may retweet if appropriate. The account is moderated and protected by the core team.
We have a Facebook page at @libraries.io. Again this is predominantly used to gather and reflect news, events and musings by contributors rather than as a direct method of communication. Contributors are encouraged to reference Libraries.io in a post when talking about the project, so that we may reflect this if appropriate. Again the account is moderated and protected by the core team.
We have a Medium account at @librariesio and once again it is used to reflect news, events and musings by contributors rather than a direct method of communication. Contributors are encouraged to reference @librariesio in a post when talking about the project, so that we may recommend it if appropriate. Again the account is moderated and protected by the core team.
Who Are Libraries.io’s Users?
Libraries.io focusses on the following personas:
Is hungry for linked data so she can serve you up search traffic
Is a developer with a problem, she is looking for something to help solve it.
Has a product or products that incorporates some free/open source dependencies. She needs to ensure the product(s) are well maintained, free of vulnerabilities and licence compatible.
Is a developer with a successful free/open source project. She’s looking to understand more about those who use her project, attract more contributors and manage their contributions well.
Has her own ideas. She wants access to the raw data so that she can mash up her own service and offer it to the world.
Has a vast empire of people, products and projects. Some of which she publishes as open source, some are proprietary. She wants to ensure that her policies regarding the use of dependencies are adhered to and that her team are as efficient as possible.
In general we use GitHub and Git to support our workflow. If you are unfamiliar with those tools then you should check them out until you feel you have a basic understanding of GitHub and a working understanding of Git. Specifically you should understand how forking, branching, committing, PRing and merging works.
We prefer that contributors fork the project in order to contribute.
We try to use principles of GitHub-flow in our branching model. That is the
master branch will always be deployable to the live site, and that every branch from that will be used to add a feature, fix a bug, improve something or otherwise represent an atomic unit of work.
We try to create an issue for everything. That is any bug, feature or enhancement that is worth an open, focussed and documented discussion.
We constrain labels as they are a key part of our workflow. Tickets will be labeled according to our labelling policy.
If it is possible to comment your contribution — for instance if you are contributing code — then do so in a way that is simple, clear, concise and lowers the level of understanding necessary for others to comprehend what comes afterward. If you are contributing code it is very likely it will be rejected if it does not contain sufficient comments.
When committing to a branch be sure to use plain, simple language that describes the incremental changes made on the branch toward the overall goal. Avoid unnecessary complexity. Simplify whenever possible. Assume a reasonable but not comprehensive knowledge of the tools, techniques and context of your work.
When adding or fixing functionality, tests should be added to help reduce future regressions and breakage. All tests are ran automatically when new commits are pushed to a branch. Pull requests with broken/missing tests are not likely to be merged.
Submitting for Review
Once a piece of work (in a branch) is complete it should be readied for review. This is your last chance to ensure that your contribution is properly tested. If you are contributing code it is likely your contribution will be rejected if it would lower the test-coverage. Once this is done you can submit a pull-request following the template.
It is likely that your contributions will need to be checked by at least one member of the core team prior to merging. It is also incredibly likely that your contribution may need some re-work in order to be accepted. Particularly if it lacks an appropriate level of comments, tests or it is difficult to understand your commits. Please do not take offense if this is the case. We understand that contributors give their time because they want to improve the project but please understand it is another’s responsibility to ensure that the project is maintainable, and good practices like these are key to ensuring that is possible.
Reviewing a PR
We appreciate that it may be difficult to offer constructive criticism, but it is a necessary part of ensuring the project is maintainable and successful. If it is difficult to understand something, request it is better documented and/or commented. If you do not feel assured of the robustness of a contribution, request it is better tested. If it is unclear what the goal of the piece of work is and how it relates to the strategy, request a clarification in the corresponding issue. If a pull-request has no corresponding issue, decreases test coverage or otherwise decreases the quality of the project. Reject it. Otherwise, merge it.
As we keep the
master branch in a permanent state of ‘deployment ready’ once-merged your contribution will be live on the next deployment.