Skip to content

Latest commit

 

History

History
105 lines (51 loc) · 9.27 KB

CONTRIBUTING.md

File metadata and controls

105 lines (51 loc) · 9.27 KB

Contributing to the Bionic Blue project

(If you want to contribute translations, check the TRANSLATIONS.md file instead)

Within a usual application project, contributions from many people are usually welcome, since the application usually employs objective measures to achieve its purposes, allowing many different people to contribute objective solutions to achieve the application's purposes. For instance, if an existing solution A is inferior to a newly presented solution B, than usually the solution B will replace the solution A.

A game project doesn't work like that, though. It has a design and set of features defined by its creator according to their vision (in this case, me, Kennedy Guerra). In other words, instead of a objective measures, it employs subjective measures to achieve its purposes. For instance, if an existing solution A is inferior to a new solution B, the solution A may still be preferred because perhaps it delivers the experinece in a particular way designed by the game's creator.

In this sense, it is not much different from a book project, which is (again, usually) not a very collaborative project, but rather the work of one or a few authors at most with help from one or few editors (I assume).

In other words, as much as we love contributions in general in the Indie Smiths project (like the several contributions made for the nodezator desktop application), for game projects we are more selective with PRs we accept.

Recently, we even turned off the pull requests tab completely, but figured out there are genuine reasons for other people to contribute code for this project, since it is free and helps so many people.

Therefore, the next paragraphs lay and explain a few guidelines to help you identify opportunites to contribute or help you assess whether your planned contribution is a good idea or not.

Ask first

Asking first is not required, but it is usually the best path. If you have game design ideas or ideas to improve/optimize the code, I'm always eager to learn about them. Consider starting a discussion for that.

The world will own your code

Remember: code merged into this repository becomes subject to its public domain licence. This means the whole world owns your code now.

A good programmer is one who understands what they are doing

According to Kanat-Alexander, a good programmer is one who understand what they are doing. This means in order to be able to do my job as an open-source maintainer, I need to understand your submitted code as well.

You will be required to further explain your solution if I, the maintainer, don't understand it or am not familiar with the concepts/methods involved. A contribution I don't understand/comprehend won't be merged.

Why?

Well, as the maintainer of the project, it is my duty to stick around and further develop the game, improve its code, solve issues, fix bugs and help people sort out problems. Perhaps in the future if I manage to get enough funding, I might even be able to hire and train other maintainers to help me. Therefore, the reason why I need to understand your code contribution for it to be merged is that, as much as I appreciate your clever contribution, I need to understand the code in order to do all those things I listed that are my responsibility as the maintainer.

For instance, how am I supposed to develop the game further or fix a bug if I can't touch a piece of code without knowing if I'll break it?

Remember: people contributing code come and go, but the maintaner is the one who sticks around and further develops the project.

Low effort PRs will be rejected

This includes:

  1. AI-generated code
  2. changes generated by linters/formatters
  3. fixing typos

AI-generated code

This project doesn't use AI-generated code. I don't even use generative AI/LLMs in its development. I'm not strictly against generative AI, it's been around for long and was usually only handled by researchers. But, then it got overhyped by people who overestimate its usefulness and underestimate its costs.

I won't explain further for now (perhaps I'll expand this section in the future). For now, the objective of this text is not to convince you of that, only to communicate my stance on this matter.

What if some code only later is discovered to have been AI-generated?

It is an undeniable possibility, one that I'll avoid at all costs. I'll do my best to prevent those, but, even in the case some such code makes into the app, it will only do so after being curated and sanitized by me anyway, in the process explained in the previous subsection ("a good programmer is one who understands what they are doing").

In other words, in the end, no real harm to the codebase itself will be done, only to the reputation of the one that submitted the code. No further contributions will be accepted from that person.

changes from linters/formatters and other tools for automatic edition

Although there's nothing wrong per se with these kind of changes, unfortunately they sometimes are abused by people who only want to feature as contributors for whatever reason.

Although there's value in those changes, there isn't much effort on the part of the one submitting them anyway, so it is not as though any other people could not do it by themselves. So please, don't submit those either.

Also, regarding formatters, although their purpose of establishing a strict consistent style in order to avoid disagreement is a noble one, in reality, at least in my own experience and particularly for the projects I maintain, including this one, not many people stick around.

Quite the contrary, I assume most open-source projects are maintained by one or a few people. Their opinion should matter and they should use the formatting that feels better for them.

It is not that I don't care for the people that inspect and contribute to the codebase occasionally, but shouldn't the people who stick around and continuously invest time and effort in the codebase be the ones whose preferences should be prioritized?

Will that many people be inspecting and contributing to the code to the point that we'd need to format it accordign to any specific standard? I don't think so. As long as we keep PEP8 compliant, any formatting should sufice.

Fixing typos

This is another category that has value per se, just like changes from linters/formatters, but that is also sometimes abused by people who only want to feature as contributors for whatever reason.

Like linters/formatters, there are also tools that can be used to automatically catch typos, so again, it is also a low effort change, not as though any other people could not do it by themselves.

People who stick around

Although it is not a requirement for contributing, people who participate in discussions or have submitted PRs before or engage with the project in other meaningful ways over time will usually have preference when it comes to having PRs reviewed and given attention to.

Of course, everyone is welcome to contribute, but keep in mind that like many open-source projects, people usually invest their time and effort with no payment. Most meaningful work, open-source or not, require time and care, so it is only natural that people who provide those things more often have their PRs prioritized.

Too many PRs (usually automated ones)

Whether from generative AI or other automation tools, something that sometimes afflicts open-source projects is the submision of too many PRs. I never experienced this, but wanted to write a policy in case this ever happens.

And my policy is simple: if the number of PRs gets too large to the point of hindering my regular development and maintenance of the project, I'll prioritize PRs according to the guidelines presented here. I'll leaving the remaining ones pending review until I can find the time to tend to them, possibly further filtering them when I revisit them.

The reason for that is that my priority is to help people by further developing and maintaining this project. Spending too much time tending to PRs to the point of hindering that is, thus, counterproductive and harmful to that priority.

There's a saying in Brazil that goes like this: "Things for which there are no medicine are already remedied.". Although similar to the "What can't be cured must be endured" saying, it has a different meaning, because in the Brazilian saying, there's no enduring.

In other words, an overflow of PRs is something problematic, but only as much as I can do something about it. If such problem ever threatens this project, I'll do as much as I can to fix it, but, in the scenario where I can't do much, I'll simply shrug and go on with my work as a maintainer, tending to the development and maintenance of the project instead tending to an unmanageable influx of automatd PRs.

As much as I love the contributing aspect of open-source projects, to me, and I think it is safe to say that it is so to most people as well, the most valuable aspect of open-source software is the delivery. That is, making open tools available to people so they can use and change them however they like.

The contributing aspect is just one of the means to that end and it is not even what sustains it. As long as there are people maintaining the project, it will endure.