Fusion
Fusion copied to clipboard
dphfox
We should take a look at our contributions process
I've heard that some people who would otherwise want to contribute to Fusion have been dissuaded by our relatively strict contributions process, specifically due to the verbosity of CONTRIBUTING.md. I'm a relatively inexperienced repo maintainer - Fusion is my first real open source project I've worked on - so I'm still trying to find a good balance between rigorous process and flexibility to accomodate for other maintainers.
These issues likely stem from my own very rigorous way of working - I want every single part of Fusion to be properly designed and accounted for, rather than letting in a massive number of ad-hoc unconsidered changes. This is the motive behind having every PR associated with a pre-approved issue; by talking about API changes as a community first, it gives us the opportunity to uncover unexpected or unseen consequences of suggestions, and perhaps explore better suited alternate solutions. I feel like this is especially valuable since I can step in as the original designer of Fusion to offer insights about how the library was originally conceived and put together, as well as ideas explored during prototyping and why they may have been rejected previously. I do not know how much of this is grounded in reality.
Something I've often observed with contributions is that they don't take a 'big-picture' approach. This isn't a knock on the quality of the contributions - we have gotten some very nicely written code - but it's often for solutions that don't really fit into Fusion's design neatly. In particular, on multiple occasions it does feel like we're getting features pull-requested that are hyper-optimised for specific use cases. I don't have a problem with serving specific use-cases necessarily, but oftentimes it's indicative that more general solutions haven't been explored. While all of this stuff can certainly be brought up in the pull request, I don't like it because someone has already invested their time and effort into making a change which may now end up completely rejected due to a lack of a design pass. I don't want to waste people's time and I don't want to insult their efforts, which is why I request that everything be designed before it's implemented. That being said, our current blanket policy of closing PRs not associated with an approved issue may also still be seen as 'disrespecting contributors' time' by the same argument, so this is also something to reconsider.
This is really thorny, because this entire issue lives at the intersection of social stuff (which I suck at, thanks asd) and technical/library design stuff (which I'm extremely passionate about). I'm not good with people, but I still want to have Fusion be open to collaboration. It's safe to say I don't have any of the answers right now, and would really appreciate some perspectives on the issue.
Like Rojo, Fusion is a library that developers rely on for their work and it exists as a core component of my project; so as a developer who uses Fusion I watch closely any changes here because I want to be ready to deal with an update and not have that fundamentally break my code.
As a result, I find it important to me that any changes are correctly QCed in a way which does promote contribution but also ensures all changes do not create a headache every update. Although being able to developers of various experience in OSS contributing should occur, as expressed in the initial issue this presents a challenge of trying the middle the line of open contribution and quality end results.
At the moment CONTRIBUTING.md is quite a heavy document in terms of the amount of text visible on the screen. But using concepts like...
Details
Which means that the document is more easily split and can adjust. Relevant Markdown doc.
as well as images and diagrams to help provide instructions to those who prefer to see diagrams than just text. Along with stuff like a table of contents to be able to quickly identify what is required to be done without reading the entire doc for a single section.
It can help give a wider range of people the ability to read this text without being immediately turned off by the process. Maybe an easy reading, content summaries, or larger line height would help.
Ultimately, it's great to reflect on the state of contribution within your project and ask for help. Sometimes you need to make it work for people at all levels, sometimes people want to know every inch of detail while some only need the overview. Being able to offer both and have that be readable to many is a great step of improvement.
Hopefully you find some use out of this.
Details are a great idea - I'll add those now since my main computer is unavailable this evening 🙂
Your CONTRIBUTING.md, as it is now, is more like a guide or checklist for you, the maintainer. This is useful information, and it's definitely beneficial to keep somewhere, but CONTRIBUTING.md needs to be written for the contributor. Keep it light enough that it can be read in less than a minute.
Don't you dare use <details>. Content inside <details> will be deemed irrelevant and will almost certainly be ignored. Personally, the idea of having to click on things to keep reading is a certain way to get me to stop reading entirely. I've said this somewhere before: <details> are for displaying mile-long tables of benchmark results. Once again, just keep it light enough that you don't even need them.
Main points to address:
- I need help
- Point to helpful resources, like your tutorials and API reference. If someone makes a good blog post or video about using Fusion, that can be included as well.
- I found a vulnerability
- Point them to SECURITY.md
- I found a bug or have a feature request
- Instead of nagging out a bunch of rules, use issue templates to guide the user.
Aside: Your SECURITY.md says,
get in contact with Elttob privately
You need to be specific here. Set up an email. Make a Discord channel. Have them message you on the DevForum. Or all of the above. Don't leave someone scratching their head.
