Contributing

oskusalerma edited this page Nov 12, 2014 · 9 revisions

Contributing changes to Trelby

The only official repository is https://github.com/oskusalerma/trelby/, and that one reflects the official state of the Trelby project. Any other repositories are development branches that have no official status and can not be relied upon in any way, as they can be ignored, rebased, lost, and so on.

Any development should be done by cloning the master repository, developing your changes, and submitting patches for review/merging.

The basics

  • Make sure you join the mailing list (http://groups.google.com/group/trelby).
  • For anything other than trivial fixes, discuss your planned work before you start development. Otherwise you might waste a lot of time developing something that will never be accepted because it doesn't fit into the project's goals.
  • One change per commit/review request. This makes reviewing them, rebasing them, merging them, and if needed, reverting them, much easier. It is also a good developer discipline on its own.
  • Clean up your development history before submitting your changes. Most changes submitted should be simple enough to collapse down to just one commit. The official history of the project does not need to know that it took you 10 attempts to get something right, it just cares about the finished product.

Coding style

  • Python 2.7 is the only supported version.
  • Lines must not have trailing whitespace.
  • Read enough of the existing code so you get to understand the formatting style it uses, and stick to that in your new code.

Testing / documentation

  • Tests must always be kept working, and new tests written for any feature that can be easily tested.
  • Documentation must always be kept up to date. It is not okay to submit a feature and say you'll write docs for it later; the doc changes must be submitted as part of the change itself.
  • If your changes make the program slower or cause it to use more memory, your change must be worth it. Use the speed test feature (see README.dev) to time the effect your changes have (running it as a baseline on unmodified code, and then against your changes), and submit those results with your patch.

Submitting changes

Always do development in branches, so you can easily rebase against master and develop multiple changes at the same time in different branches.

git clone https://github.com/oskusalerma/trelby.git
cd trelby
git co -b mychanges
... make your changes ..
git commit
git format-patch master

Submit the generated patch for review to the mailing list, or push it to your github fork and send a pull request. Either way is fine. Make sure your patch applies cleanly against latest master.

Git commits

  • The first line of the commit message should be shorter than 70 characters.
  • The second line should be blank.
  • Any additional lines should not exceed 74 characters.
  • Have the author field properly filled out with your full name and email address.
  • Use active present tense. So say "Fix hyperspace engine blowing up at warp speed", not "Fixed..." or "Fixes...".
  • Use proper capitalization and end sentences with a dot.
  • If your change fixes an issue in the github issue tracker, put "Fixes #XXX" where XXX is the issue number at the end of your commit message. This tells github to close the issue automatically and link to the commit from the issue.

Guidelines

These are some things to consider before thinking about modifying the code:

  • Does your change fit the general goals of Trelby? Trelby is a multi-platform, lightweight, simple screenplay writing program. Your change should not contradict this. Examples of things that would conflict with our goals:
  • Platform-specific features that would make the program behave wildly differently on other platforms.
  • Complex features only needed in the production stage of a screenplay.
  • Niche features used by 0.1% of scripts. Example of this would be dual dialogue, which adds huge internal complexity to the program, but is used in actual scripts with extreme rarity.
  • If you change the script fileformat (not to be done lightly), you must support all the old fileformat versions as well, forever.
  • Is your patch cross platform? Will it work on both Windows and Linux?
  • Is the feature broadly useful? There's no point adding features that only you or a few people will use.
  • Will this patch create more work for the Trelby developers? In short, is it adding to complexity?
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.