*NEW 2015/9/4* Code submission guidelines (crosspost)

Like feature suggestions, but you've actually written code to make it happen. More likely to make it into the game than some random request in feature suggestions.

Moderator: GZDoom Developers

Forum rules
Please see Code submission guidelines

GZDoom Status:
Image

Legacy Status:
Image Image

QZDoom Status:
Image
User avatar
Rachael
Posts: 13531
Joined: Tue Jan 13, 2004 1:31 pm
Preferred Pronouns: She/Her
Contact:

*NEW 2015/9/4* Code submission guidelines (crosspost)

Post by Rachael »

(crossposted from here)
Blzut3 wrote:Congratulations on the decision to contribute to ZDoom! In order to expedite your code submission, please take note of the following guidelines. For experienced programmers most of the following will be obvious. For those of you new to programming, ZDoom is an excellent project to get started working with real world code. You should always keep in mind that you're dealing with a project which has a large history, a large number of users, and relative to most other open source projects a large number of developers.

Several of the following guidelines are written using terminology for feature requests. Most people start contributing by adding new features, but if you are submitting bug patches some of these guidelines are do not apply. You should submit any bug fix patches in a proper bug report thread.

You are required to have a development environment!
There are guides on the wiki on how to compile ZDoom for all supported platforms. You are expected to have compiled AND verified that any code you submit is functional. Do NOT submit code on behalf of other people for any reason. We're all human and we understand if you accidentally forgot to add a file to the repository and that your code may have bugs. As experienced developers we can tell the difference between this and blind programming. If we find that your code quality is consistently bad, you can expect that complex patches from you will be rejected.

Code sanitizer/static analyzer is not an excuse to contribute
If you don't know what you're doing, do not use these tools. We typically find that people who use static analyzers as an excuse to contribute apply the wrong fix. Similarly reporting the errors to us isn't especially helpful as it can become a cat and mouse game. We're not saying they're bad tools, but use them in your own projects first.

We prefer GitHub pull requests
Please consider getting a GitHub account and forking the ZDoom repository. It is not a requirement as you can submit patches via this forum, but it makes our lives easier. Make things easier for us and your code is more likely to be accepted.

Additionally create a thread on this forum for your pull request which include links so that we can easily keep track of both threads of communication. GitHub notifications have a tendency to get lost.

There is no promise of acceptance
While we're more inclined to add features if the work is already done, features will still be evaluated in the context of maintenance and/or performance cost. If there is an implementation design issue, we may provide suggestions on how to improve the design. You are, however, expected to do your own problem solving as this is not a way to force the developers to implement your feature.

Partial solutions will often be rejected as they pose a high risk for backwards compatibility issues.

Commit history is good, but keep it useful
If a patch needs to be completely redesigned. Please discard your pull request and start fresh. We aren't going to ask you to send us only one commit, but the history shouldn't be full of reverts and retries. That history just isn't useful. It is desirable that all commits compile and run as it makes it easier to track regressions.

Additionally, please be sure to write descriptive commit messages for all commits.

Justify your features
Just because your wrote the code doesn't mean you're off the hook as far as justifying why you need the feature. If the only reason we can determine you wrote the feature is "because I can" then the patch will be rejected. A justification is more than simply describing the semantics of your new feature. Tell us what cool things the feature would enable.

If you're submitting a complex feature consider leaving us with a demo wad.

Blend in (code style)
ZDoom's programming style isn't perfectly consistent, but it's consistent enough. Follow the style of nearby functions and blend in. In general here are some rules:
  • Use tabs for indentation. Tab size is 4 spaces.
  • Braces go on a new line.
  • Function/method names are capitalized (camel case). This is SomeFunction rather than otherFunction.
  • Avoid C++ STL. It's not banned, but TArray, TMap, FName, and FString are probably what you're looking for. In general if it's not <algorithms> you probably shouldn't be using it. Basically familiarize yourself with name.h, tarray.h, tflags.h, templates.h, and zstring.h
For the curious the F prefix on classes/structures comes from Unreal Engine.

Stay focused
Bundling multiple features and fixes into a single pull request will lead to it being rejected.

Do not include any code style changes unless you are doing refactoring (unless you're a trusted programmer (see next section) you probably shouldn't be doing refactoring).

Double review
Your feature submission will need to be approved by two developers before being merged. In lieu of approval from a second developer, a trusted programmer can choose to sign off on pull requests including their own. The exceptions to this rule are:
  • It is a bug fix.
  • The feature is deemed trivial.
Trusted programmers: Edward850, Gez, _mental_ (Alexey Lysiuk), Nightfall/Dusk, Torr_Samaho

The people listed above have demonstrated that they have a deep understanding of the ZDoom code base and generally do not require feedback on their submissions. Getting on this list is not a requirement to gain access to the developers forum, which is available to frequent contributors by asking Randi for access.

Return to “Code Submissions”