Code design workflow

From Post-Apocalyptic RPG wiki

Jump to: navigation, search

Established workflow.png This article covers an established workflow.

Established workflows have been discussed among and agreed upon by the development department(s). They should serve as documentation how these workflows are successfully utilized in the project.

This page describes the process for contributing changes to PARPG's codebase.

Contents

General Workflow

In general, we expect contributors to follow this general workflow when submitting code patches:

  1. Hop on IRC or the forums and announce your intension to make some changes (not necessary for minor changes, but encouraged);
  2. Add a Trac ticket describing your proposed changes as documented in Programming:How_to_use_Trac;
  3. Write up some designs or start prototyping your changes, and share your results by attaching comments to the Trac ticket you created above;
  4. Test your changes! Write unittests and/or functional tests, if necessary;
  5. Attach a patch with your changes to your Trac ticket (see the Patches article for instructions on how to create a patch);

One important point: your code must not break the current functionality of PARPG! So make sure to test your code. Patches that break PARPG will almost certainly not be accepted.

Your patch may contain errors and poor code. Everyone's patches suffer from this to some degree, and that is why we emphasize communication and code review. If you haven't dealt with this before, remember not to take it personally. Just think of it as a really good compiler/lint examining your code to help you do the best possible work.

Please check out our Coding standards and best practices and respect those standards when submitting patches, even if you disagree with them. If you strongly disagree with our coding standards and feel that you have a better way of doing things, then write up a proposal and discuss it (politely!) with the current developers. But do not expect those changes to be implemented without a very strong argument to back you up.

Minor Changes

Minor changes include bug fixes, code/code documentation cleanup, and minor optimizations. Generally minor changes do not introduce new features or change the code API.

Minor changes usually don't require much code review, so if you find a bug or spot some kludge in a function go ahead and send in a patch. Chances are good that a developer will take a quick look and apply the patch immediately.

Major Changes

Major changes are basically any change that affects more than one function, that changes the API or that introduces one or more new features.

If it's a major change or addition, then we assume that it's already on the list of Current tasks on the wiki or as a ticket at Trac. If it is not a planned change, then it is essential that you get in contact with the current developers via the forums or IRC to make sure that no one else is working on the same thing and that your changes would be worth while.

Contributors who wish to make major changes to PARPG are encouraged, though not strictly required, to draft a written proposal describing the changes and the positive and negative effects of those changes. Proposals belong to their own page on the wiki, and should contain a "{{Active_Code_Proposal}}" tag at the top so that it appears on the Code proposals article. The proposal doesn't have to be super detailed or 10 pages long, but do organize it by section and run spellcheck before posting it.

If In Doubt, Communicate!

Although we're flexible about code design workflows in terms of whether contributors like to design or prototype first, we do expect contributors to communicate with the PARPG developers and with other contributors! Communication skills are essential to coordinating team effort and getting things done in a way that doesn't slow the project down or make things confusing for the rest of us.

We do expect contributors to have basic writing and communication skills. Knowledge of UML and flow charts is helpful, though not required. If you prefer to communicate with code then use PARPG's pastebin and post a link on IRC or the forums.

We have multiple mediums for communicating your ideas with the rest of the PARPG team. If you prefer asynchronous communication the PARPG forums or wiki are the best places to go. If you prefer live communication then hop on IRC and chat with developers and other contributors to get comments on your ideas.

Don't be shy! PARPG has contributors with various skillsets and levels of experience, and we try very hard to create an inclusive and friendly community. Do come prepared to discuss your ideas and get feedback though, as that is what a team project is all about.

Personal tools