Plugin collaboration

What is a patch?

A patch is an update to a plugin. Patch functionality can be used by developers to submit updates to plugins that allow collaboration (directly on uMod.org).

Who can patch?

Developers must have at least one plugin published on uMod.org to access patching. Patching must also be enabled on each individual plugin (it is enabled by default).

Why submit a patch?

Programming is a time-consuming and difficult discipline where even the best programmers cannot predict all bugs or edge-cases.

The "scope" of a plugin is essentially what the plugin "intends to do". Usually the scope of a plugin will be narrow at the beginning and become wider with time. As a plugin becomes larger and more complex the probability of bugs increase.

It is less likely that bugs will remain unaddressed with more eyes exploring the code. Also, by spreading out the task of development, it is more likely new features and improvements will be added.

Recognizing the value of collaboration in plugin development and allowing other developers to submit patches can greatly improve the quality of code over time, not to mention build relationships in the community.

Local forks

It is naturally tempting for developers to imagine that they might add functionality to an open-source plugin and keep it to themselves to create an advantage over their competition.

Every plugin has room for improvement and no plugin is ever really "finished." The scope of a plugin can always be changed or expanded. For this reason opportunities to establish some competitive advantage are endless.

However, a couple of common problems arise from this approach:

1. A local fork routinely becomes out of sync with the official upstream. When a plugin is updated the local fork must a) incorporate the official changes into the fork or b) create a new fork and re-add the local changes. This may not be a big problem for 1 or 2 local forks, but after 3 or more local forks this process can quickly become a considerable task. Whatever temporary advantage a local fork may have had is quickly lost when the official plugin is updated routinely and valuable development time is consumed staying in sync with the public version.

2. Plugin development is incremental and usually potential improvements are obvious to anyone who cares to look. Instead of having 10 different developers duplicating effort to make the same modification 10 times, it would be a better use of time to have 10 developers working together to make 10 different modifications and building on previous improvements each time.

Designing for collaboration

Code is simply a set of mathematical instructions for a computer to process and high level languages (like C#) often have many different ways to achieve the same outcome. Quite often beautiful code can be slow and fast code can be ugly. There are a variety of concerns behind every line of code that may not be obvious. High level languages are versatile and can be as expressive as poetry with seemingly infinite layers of abstraction designed to put machine language in terms that the human brain can understand.

It can take a decade for an individual to master even a small slice of the computer science field. Crowd-sourcing and collaboration helps relieve this burden by enabling an individual to benefit from the accumulated wisdom of the crowd. Certain practices can ensure collaboration remains easy and fun..

1. Comments – Information surrounding code that describes what code does. Comments should be imperative, terse, and concise. Not everything needs to be commented, but key functionality ought to be accompanied by some natural language describing it.
2. Organization – Code ought to be separated into small easily digestible classes and methods (i.e. SOLID). Further, classes and methods that are similar should be grouped together and in regions.

Designing for integration

A plugin should not try to be everything to everyone. Scope creep is a natural occurrence in plugin development but by adding key integration points and splitting a plugin into smaller separate plugins the task of maintaining plugins can be kept manageable as more things are added.

It also helps to have an idea of existing plugins that already fulfill similar needs. If possible, integrate with those plugins rather than duplicate work.

Conventions and style

Coding conventions and style guidelines are largely subjective and vary greatly depending on 2 things:

1. Programming languages are very different and developers are often familiar with multiple languages. A programmer who has significant C++ experience may have very different ideas about how code should look compared to a Java developer. Though uMod is a C# platform, developers should, and often do, branch out into other languages and platforms.
2. Object-oriented versus procedural versus functional programming preferences. Certain programming languages tend to focus on one type of implementation over another and C# is very versatile by allowing all 3 approaches. There are pros and cons to each approach and considerable literature out there about the differences, however it should be noted that one approach is not necessarily "better" or "worse" than another.

Naturally we recommend becoming familiar with standard C# coding conventions, but these conventions are still subject to debate and there is disagreement in the C# community about them.

Context is incredibly important when tackling any given coding problem and every developer comes into a project with different experience, preferences and constraints. Human beings are not computers and it is important to recognize that it is very difficult to criticize code with a completely mathematical, objective, and unbiased perspective. It's also important to acknowledge that this does not mean any given criticism is invalid, only that developers ought to take great care to differentiate between their opinion and objective reality.

When criticizing another developers code...

1. Stick to the facts. Criticize the code, not the person.
2. Use language carefully by adding qualifiers like "in my opinion" or "from my experience." Even if the criticism is 100% objectively valid, these qualifiers can help keep discussion civil.

Keep it simple

A large plugin can be intimidating or represent a significant investment for other developers to learn. Usually other developers have a very narrow idea that they want to implement and if confronted with a massive plugin many developers might abandon the idea rather than make the attempt. Keep it as simple and organized as possible, if not just for them, but also for you when you come back to the plugin in 6 months having forgotten what you did or why you did it.