Skip to content

Contribution Guidelines

Jump to bottom
Tom van Dijck edited this page Jun 26, 2017 · 4 revisions

This is still very much a work in progress. If you would like to comment or offer feedback, please do so in the discussion forums rather than editing inline, so we can try to keep this somewhat manageable. Thanks! —<>

Some Examples

Here are contribution guides from some other projects that we can use as examples while writing this one. Feel free to chip in make improvements to help those who come here after you.

Configuring Git

Premake uses Git as its source control system, hosted by GitHub. If you are unfamiliar with Git, there is a collection of guides, videos, and the official documentation to help you get started.

We recommend the following configuration, which can be made globally by editing ~/.gitconfig on Mac OS X and Linux, or C:\Users\<your user name>\.gitconfig on Windows.

At a minimum, you must set your user name and email address, to identify yourself as the author of any commits you make.

[user]
    name = Susan Example
    email = [email protected]

Contributing to Premake

If you would like to get more involved with Premake, and begin making contributions to our code on a longer term basis, you should take the following steps:

  1. Create an account on GitHub.
  2. Go to the premake-core repository and click on the fork button.
  3. Clone your forked repository to your local machine.
  4. Make a topic branch for individual features or fixes {{{git branch newfeaturebranch}}}
  5. Make the necessary changes. staying focused on a single feature or fix. Do not mix multiple features or fixes in the same branch; instead create a new branch for each.
  6. Commit your changes and git push
  7. Make a pull request to premake-stable if your patch fixes a bug and does not introduce any new features or API changes, or to premake-core otherwise.

For more information, see GitHub Bootcamp.

While getting used to Git there are several guides... You can also ask questions on IRC (#premake on freenode.net) or our mailing list.

Recommendations

  • Don't mix unrelated changes in a single patch. In particular, don't change formatting of unrelated code even if you see it does not follow out coding style. If you intend to fix a bug, make sure your patch is minimal so it can be applied to stable branch without risk of introduction of new bugs.
  • If you develop new feature, prefer to submit it as a single commit. Ideally 1 commit = 1 independent feature or 1 bugfix.
  • Write tests. This isn't strictly required, but if you don't your contribution will be held up until someone does.
  • Don't break API compatibility with previous Premake versions when possible.
  • After submitting the pull request, ask for feedback on the forums

Coding Standards

  • The Lua standard for names is all lowercase, all one word: dosomethingcool. If you are creating a new project scripting API, or a function that will be visible to the project scripts, try to use this convention. Everywhere else, I'm switching to the much more readable pascal case: doSomethingCool; use this for symbols that will only be visible internally or to add-ons.

  • Use tabs for indentation, not spaces.

  • Use Unix (LF) style newlines.

Clone this wiki locally