Links
🚁

Contributing

Welcome!
Thanks very much for interest in contributing to Jet, we are happy to have you here! This page serves as a guide for understanding how to work with the project. Development topics are covered later on in the documentation -- this chapter is more process and philosophy related but is equally important.

Commentary

Balancing Growth And Focus
If you would like to contribute to Jet (thanks!!!), we want you to know how we expect things will play out.
We work differently than some GitHub-first projects you may have worked on in the past, as we are designing our community workflow to enable (potentially) high contribution volumes and long term maintenance of all contributions. We have a lot of experience in this (and the need for this) from past projects.
It is important to underscore that Jet is foremost an open community project and will always be greatly appreciative of all contributions. At the same time, Jet wants to have a professional and robust "flavor" (hopefully this is apparent!) and will always seek to retain and strengthen that commitment even at the expense of greater adoption or features.
Therefore, development of Jet must balance these two forces and not succumb to a desire for feature-sprawl or popularity at the expense of usability and quality. As such, the standard for successful merging of code additions will not be impossibly high, but it may be significantly higher than some other projects.
While we believe that many features will be easy to develop based on the architecture of Jet, it's also true that sometimes simple things become more involved than they first appear, because they must be done a certain way and to a certain degree of completeness, clarity, consistency, and attention to detail. We do this to plan for future development and upkeep - accepting every feature comes with an upkeep cost.
We want to look at open source software as building an architecture of surprise and possibility and making a "fun" community to be a part of, but also look at our job as being stewards of the project's original and constant goals. The program's code and quality will always matter the most, more so than the temporary good feeling of getting a pull request merged. This balance runs through everything we do.
As it is important to preserve the minimalism, security focus, and attention to detail of Jet, this may mean saying "no" more often than some may expect or want. We want to consider nearly all ideas and grateful for all of them. When we decline an idea, it's not about the idea or some code being uninteresting or inappropriate per se, but the larger picture of long-term upkeep needs and surface area -- and sometimes about learning experience.
If deciding to not implement some idea or take some code contribution, we'll always explain our reasons and can be persuaded in many cases to change our mind. However we can seldom ever persuaded to break existing users or do something that will potentially enable hard-to-maintain automation content, even when that feature is powerful and exciting.
If potential contributors understand these factors going in, we should have a great experience working together, and will always work hard to make that a rewarding experience.
Communities Extend Beyond GitHub
In the rest of this guide, there's a large emphasis on communication outside of GitHub. We believe GitHub is just a tool, and we think it has mixed effects on open-source development. We want to bring back a bit of the pre-GitHub open source development atmosphere where conversation typically happened over chat or email before deciding what to do with a patch set and users and developers got to know each other a bit more.
Interactions before GitHub were usually about exploring ideas around implementation first and code submissions came afterwards. Often having more group communication produced very interesting ideas and interaction was less isolated. Communities were more community-oriented and less made of marketing buzzwords. Often, because contributions were discussed in advance, there was less conflict when trying to figure out if a contribution was wanted, or how it should be shaped, and many efforts were a lot more efficient, rather than leaving pull requests in queues for months at a time, as has unfortunately become the norm for all too many projects. This is an experience we believe is deeply unfair to all involved.
We'll still use GitHub for pull requests and tickets of course, but want to emphasize that we think open source is better when more up-front communication happens and things are a little bit friendlier, so we've picked Discord to be our interactive communication platform, and aim to keep our GitHub queues always moving quickly.
Simplicity Of Process / Commitment To Contributors
We do not have any governance boards, committees, steering groups, votes, checklists, need for approvals on PRs, CLAs, bots (we are very much anti-bot), scheduled meetings, meetups, conventions, working groups, employees, or language feature review processes. It's really just this - talk about things on chat first, do good work, always make sure we are doing the best possible thing, and plan for the future - so not that bad really!
Servant leadership is very important to us. We therefore aim to keep our bug queue short and well managed, and not leave people waiting for months in between trying to help out with an idea. We will favor getting things done over bureaucracy and formal process at all times.

How To

How To Submit Bug Reports
Nothing new here! Please submit bug reports on GitHub. If you are not sure if something is a bug, you are welcome to stop by Discord to discuss it, but this is absolutely not required.
Do not assume any short replies on GitHub - which we'll try very much to avoid wherever we can - are anything other than us being busy - and if you have any problems, feel free to reach us on chat - especially if you disagree with one of our conclusions or something remains a problem or you disagree with a ticket being closed. We may not always see GitHub notifications, especially on closed tickets, so stopping by chat is often helpful. Thank you very much and we greatly appreciate all reports!
How To Ask User / Support Questions
Regardless of your question or problem, we want to help you out.
The best place to ask questions is Discord, so please do not ask user/help-related questions on GitHub as you'll be directed to Discord. Should questions or communities arise on other forums (serverfault, reddit, etc), we will not have time to participate there - there are just too many venues and this would take time away from paying attention to Discord and working on the project, so again, we recommend joining chat instead. Having questions posted on chat also allows other people to see the questions more easily, and also help in answering them!
The GitHub tracker is unfortunately not a good place for involved discussion and we don't want to frustrate anyone by closing unresolved questions or frustrate ourselves on having a large queue of questions that we don't know when to close mixed in with other tickets. Because of email volume, we do not read any notifications on GitHub or see comments on closed tickets, so everything we do is optimized around keeping the github open issues queue very short.
A paid email support option for companies most likely will be available at a later date in the coming months, but does not currently exist (and we're too new right now anyway). Best-effort chat support will always be offered for free no matter what happens. We can't really manage one on one free email support, and not wish to manage a mailing list (nor do most people want to join one), and would like everybody to be able to see (and help answer) questions.
If questions come up frequently in Discord chat, we will always try to work those answers into the documentation to minimize future questions so that we can continue to scale - and less questions have to be asked!
Thank you and if you're willing to join chat we'll get you sorted out!
How To Submit Pull Requests For Bug Fixes
Thanks very much for wanting to fix something! If you would like to submit a change for an obvious bug, you can submit it directly on GitHub if you want. Depending on the fix, talking about the code first in chat may still be helpful.
Try to keep code changes minimal, clean, and non-invasive as best you can, please do not refactor or restructure code in other areas of the program unrelated to the bug fix, even though you may very much want to. We'll say it again elsewhere, but also please turn off auto-formatting in your code editor.
Please be sure the code remains free of warnings and handles all possible errors appropriately as explained in the development guide. We do not 'web-merge' any Rust commits and need to do our own testing, so we really don't want to see warnings when we fire up the compiler! Your thorough testing of your code on affected platforms is required to also be respectful of our time.
We don't want to be too particular with git practices as we think git is often too complicated ourselves. Try to rebase your commits the best you can and squash things down to a single commit, or if it's a larger fix, various smaller commits that explain the steps are ok. We're not too picky there but a bug fix should really only be one or two commits. Merge commits should not be in your pull request.
If there is code you don't understand, we recommend asking questions on Discord (git questions are fine too!), and we'd be happy to explain absolutely anything about the source. The more people who understand Jet's code the better!
How To Submit or Discuss Feature Ideas / Requests
Ideas are very very welcome and we basically live for idea discussion! Stop by Discord and we want to talk about your idea.
To keep our tracker clean, we do not accept or record requests-for-enhancement (RFEs) on GitHub. The tracker is for bug reports and pull reuests only. Ideas may either get added to the roadmap or if you are considering contributing a feature, we can discuss what shape it might take. All planned features are also not necessarily on the roadmap. Also, because we don't do something today doesn't mean we might not decide to do it tomorrow!
It may happen that we may say no to an idea to keep things focused in the problem or because we don't want to maintain some code. In that case, external modules may be a good fit if the idea was module related. If we're not super interested in a good idea, it may be there other priority tasks for us to work on at the time but it would still make a good contribution item for you to work on.
How To Submit Pull Requests For Features
Everybody loves features and we want to hear your ideas! To be respectful of everyone's development time and particularly yours, we suggest not sending a pull request for a feature without first discussing it on Discord prior to working on it, at least minimally. This includes module submissions to see if they are a good fit for Jet or not. In short, don't do what GitHub tends to encourage and "throw code over the wall".
Why is that? Well, we want to make sure features are a good fit for the program and also don't want to have to describe how we might want something reworked if we can instead we can talk first about how to build it a certain way the first time. This saves everyone work across the board to talk about things first. We also want to help avoid duplicate efforts when we know something may already be in progress or have particular plans for it.
Be sure to make sure your submission handles every possible error or input/output scenario correctly on all possible platforms. Submissions should not be proof of concepts and should aim at being relatively impervious to error conditions.
We know the feeling of sending a PR only to get it rejected or to be asked for tons of changes and never get it merged or that talking weeks - those are all terrible things. We're seeking to avoid that as much as we can. We absolutely don't want to hurt anyone's feelings by leaving their pull request sitting in limbo for two months while constantly asking for it to be re-based. Nothing is fun about that - up-front conversations are great and make things easier!
We don't particularly love GitHub PRs for lots of back and forth discussion, it feels too much like a message board or somehow too formal, so it's better to have chat for that up-front. There may still be some small follow up comments on the GitHub pull request, and it may still be useful to discuss the PR in chat depending on complexity. Basically, the project does not revolve around GitHub, it revolves around Discord and the Substack.
We very much look forward to working with you!
How To Submit Documentation Errors, Comments, or Changes
Suggestions for changes to the documentation can be submitted on GitHub or discussed on Discord, Discord is probably easier but either is fine.
Documentation is maintained in GitBook and it is not possible to submit a change to the documentation via pull request directly since GitBook synchronization is not bi-directional, and we've chosen to use the web editing features to make it easier for us to write more and better documentation faster.
This is a little bit of a weird thing, but ultimately GitBook is a huge win for the project over other documentation systems. If you are trying to add a suggestion for some new docs, feel free to write up some of the suggested text and send it to us in a ticket. You don't get any GitHub PR gamification stats but we will appreciate you just as much.

Other Topics

I Don't Know What I Want To Do, But I Want To Help?
If you want to help work on something and don't know what to work on, unfortunately, we can't really help with that too much -- but we do want you to get involved! It's a frequent question in many projects, and while we appreciate the interest, we can not assign tickets for people to work on.
The best open source additions are for things that you want and need. If there are an open and unassigned bugs, this might be a good target, or perhaps you could try your hand at writing a module for your favorite operating system... but please stop by Discord first to see if the idea would be a good fit, as we want to be respectful of everyone's time and don't want to reject anything after the work is done, because as mentioned above, that's a terrible feeling for everyone. If you have a particular need, scratching your own personal itches are always the best contributions!
If you want to do something that we for some reason do not want to include, external modules will fill a strong void for when someone wants a module and we don't think it woul d be a good fit for the core program. The whole idea is to enable that possibility so the system remains open ended while still having strong opinions.
Avoiding Trivial or Unwanted Commits
Hopefully this doesn't apply to anyone reading this, but we are sharing this after much experience running some very active projects on GitHub.
This project is not interested in participating in github gamification, but chooses to use GitHub merely because most people have user accounts there and the pull request tools are slightly better. Please do not submit any of the following as they will be closed, and they take valuable time away from the product's development and communications with serious users:
  • Code reformatting changes - this breaks attribution in commits and often impairs readability. While many may strongly believe in their own preferences, all preferences are subjective. Code formatting will be discussed in the development guide. Please turn off all auto-formatting in your editor. Debates about coding style are not productive.
  • Trivial spelling corrections - we'll fix them probably, but we're also unlikely to merge them and would prefer you engage with the project in a more serious way.
  • Results from auto-linters or correction programs, especially those generated from bots.
  • Refactoring issues that are matter of stylistic or personal preference, unless discussed first. This does not include fixing our Rust code where you can explain why the fix is functionally better/useful and simpler, but we still recommend discussing it in chat first. Code changes always require lots of extra testing. We don't mind learning new tricks - but are concerned about readability, so more concise methods are not always better (this may include things like using map_err instead of match, etc). We may have reasons for preferring the particular way something is done and find it more readable. Code that must be unrolled to be worked on and then reassembled is almost always worse, and it gets tiring explaining choices when denying pull requests of this nature.
  • Introduction of new libraries dependencies, unless discussed first - we're probably open to things, but want to make sure we understand all the things used, and may ask for something to be implemented a different way. An active maintaince history is very important, and each new dependency can be a liability. It all depends on how easy it is to remove and whether it affects the user surface area of the program if it were to be removed. The more invasive a dependency is or the harder it would be to replace increases the likelihood that we would not want to include it. Dependencies must generally have a large followings and a stable maintaince history to merit adoption.
  • Introduction of async in Rust beyond the existing usage of rayon
  • Changes to .gitignore files or other dotfile additions for your editor, personal tools, or favorite build systems that clutter the repo root.
  • Any code you did not test (including error paths), breaks compilation, or adds warnings.