Contributing to the TRIP Guides
This guide covers how you can become a part of the ongoing development of the TRIP Guides.
After reading this guide, you will know:
How to contribute to the TRIP Guides.
How to use GitHub to create an issue.
How to use GitBook to create a guide.
TRIP is everyone's protocol. So far, dozens of people have contributed to the TRIP Guides ranging from a single character to massive protocol design changes or significant documentation - all to make TRIP better for everyone. Even if you don't feel up to writing code or documentation yet, there are various other ways that you can contribute, from proposing guides to building the community.
As mentioned in TRIP's README, everyone interacting in TRIP and its sub-projects' codebases, issue trackers, chat rooms, discussion boards, and mailing lists is expected to follow the TRIP code of conduct.
Contributing to TRIP
The Rideshare Protocol (TRIP) is an open protocol.
What is an open protocol?
Well first, a protocol is a way computer programs talk with each other. And a protocol is open when the computer programs don’t need permission to talk together.
For example, the web is an open protocol. Any web browser can “talk to”, or view, any website.
And because of this, open protocols like the web, allow for permissionless building. Meaning anyone with the technical knowhow can build a website and add it to the web.
So using the same reasoning, anyone can contribute to TRIP. Today, one of the best ways you can contribute to TRIP is by creating content that helps people share TRIP effectively.
To more effectively coordinate the community's efforts, we have created the TRIP Guides you are reading here. TRIP Guides are designed to help you share TRIP effectively, and to help you understand how all of the pieces fit together.
Anyone, including you, can create new TRIP Guides or edit existing ones.
Proposing a Guide
TRIP uses GitHub Issue Tracking to track proposals of new TRIP Guides or edits to existing ones. If you feel something's missing from the TRIP Guides, this is the place to start. You'll need to create a (free) GitHub account to create an issue or comment on issues.
NOTE: Guides related to the goals of the TRIP core team will likely get the most attention.
Creating an Issue
If you feel something's missing from the TRIP Guides, search the Issues on GitHub, in case it has already been proposed. If you cannot find any open GitHub issues addressing the issue you've identified, your next step will be to open a new issue.
We've provided an issue template for you so that when creating a proposal you include all the information needed to determine whether a new or edited TRIP Guide is needed. Each issue needs to include a title and clear description of the proposal. Make sure to include as much relevant information as possible, including examples, templates, or evidence from users to support your proposal, as well as your own reasoning. Your goal should be to make it easy for yourself - and others - to agree with you and figure out the best solution.
Once you create an issue, it may or may not see activity right away. That doesn't mean other people don't care about your issue, just that there are a lot of issues to get through. Other people with the same issue can find your issue, confirm it, and collaborate with you on addressing it. If you know how to address the issue, go ahead and open a change request in GitBook (not in GitHub).
Helping to Address Existing Issues
Beyond creating issues, you can help the core team address existing ones by providing feedback about them. If you are new to TRIP core development, providing feedback will help you get familiar with the protocol and the processes.
If you check the issues list in GitHub Issues, you'll find lots of issues already requiring attention. What can you do about these? Quite a bit, actually:
Confirming Issues
For starters, it helps just to confirm issues. Do you agree with the issue author? Can you provide additional examples, templates, or evidence from users supporting the issue? If so, you can add a comment to the issue saying that you're seeing the same thing.
If an issue is very vague, can you help narrow it down to something more specific? Maybe you can provide additional information to confirm the issue, or maybe you can eliminate unnecessary steps that aren't required to demonstrate the problem.
If you find an issue without an example, template, or evidence from users, it's very useful to contribute some or all of these elements. This is also a great way to explore the protocol: looking at existing examples, templates, and evidence from users will teach you how to prepare your own.
Anything you can do to make issues more succinct or easier to understand helps folks trying to write or edit Guides to address what's missing - whether you end up writing the content yourself or not.
Commenting on Change Requests
You can also help out by examining change requests that have been submitted to TRIP via GitBook. You'll need to create a (free) GitBook account to comment on existing change requests, create a new Guide, or edit an existing one.
Here are some things to think about when commenting on change requests:
Does the change request actually address a proposal in GitHub issues?
Does the change request address one (and only one) proposal in GitHub issues?
Are you happy with the change request? Can you follow the writing? Is there anything missing?
Does it have a clear justification? Should documentation elsewhere be updated?
Do you like any included examples or templates? Are any examples or templates missing? Can you think of a better or more effective example or template?
Once you're happy that the change request contains a good change, comment on the change request in GitBook indicating your findings. Your comment should indicate that you like the change and what you like about it.
Something like:
I like the way you've restructured the content in "How to sign up drivers" — much nicer. The examples look good too.
If your comment simply reads "+1", then odds are that other reviewers aren't going to take it too seriously. Show that you took the time to review the change request.
Write Your Content
Now it's time to write some content!
When making changes for the TRIP Guides, here are some things to keep in mind:
Follow the TRIP Guides style and conventions.
Use the TRIP Guides idioms and naming.
Update the (surrounding) documentation, examples elsewhere, and the guides: whatever is affected by your contribution.
TIP: Changes that are cosmetic and do not add anything substantial to the understanding of TRIP will generally not be accepted.
Follow the Writing Conventions
The TRIP Guides follows a simple set of writing style conventions:
Limit the use of adverbs.
Limit the use of passive voice.
Short words are best. Old words when short are the best of all.
The above are guidelines - please use your best judgment in using them.
Additionally, we recommend using Hemingway to improve the readability of your contributions. Please copy and paste your writing into Hemingway before submitting a change request. We also recommend reading The Elements of Style to improve your writing further.
Commit Your Changes
When you're happy with your writing, you need to request a review of your change request in GitBook.
Before you request a review of your change request in GitBook, write a commit message for it in GitBook. The commit message should include a clear title and a link to the related GitHub issue.
Then in the related GitHub issue, write a well-formatted and descriptive comment. This is very helpful to others for understanding why the change was made, so please take the time to write it.
A good commit message looks like this:
A good descriptive comment looks like this:
Once you have a good commit message and comment written, you're ready to request a review of your change request in GitBook.
Get Some Feedback
Most change requests will go through a few iterations before they get merged. Different contributors will sometimes have different opinions, and often edits will need to be revised before they can get merged.
Some contributors to the TRIP Guides have email notifications from GitBook turned on, but others do not. Furthermore, many who work on the TRIP Guides are volunteers, and so it may take a few days for you to get your first feedback on a change request. Don't despair! Sometimes it's quick; sometimes it's slow. Such is the open source life.
If it's been over a week, and you haven't heard anything, you might want to try and nudge things along. You can use the TRIP Community on Telegram for this.
You can also leave another comment on the change request.
While you're waiting for feedback on your change request, open up a few other change requests and give someone else some! They'll appreciate it in the same way that you appreciate feedback on your edits.
Note that only the TRIP core team is permitted to merge change requests. If someone gives feedback and "approves" your changes, they may not have the ability or final say to merge your change.
Iterate as Necessary
It's entirely possible that the feedback you get will suggest changes. Don't get discouraged: the whole point of contributing to an active open source project is to tap into the community's knowledge. If people encourage you to tweak your content, then it's worth making the tweaks and resubmitting. If the feedback is that your content won't be merged, you might still think about releasing it independently on your own social media profile or site.
TRIP Guides Contributors
All contributions get credit in the TRIP Guides Contributors.
Feedback
You're encouraged to help improve the quality of this guide.
Please contribute if you see any typos or factual errors. To get started, you can read our Contributing to the TRIP Guides section.
You may also find incomplete content or stuff that is not up to date. Please do add any missing content by creating a free account in GitBook.
If for whatever reason you spot something to improve but cannot do it yourself, please open an issue.
And last but not least, any kind of discussion regarding TRIP documentation is very welcome in the official TRIP Community on Telegram.
Last updated