How to work with proposals

This article describes the rationale for writing proposals, some guidelines on how to write them, and elaborates on the different proposal types.

Why write proposals?
Proposals are suggestions about introducing substantial larger changes to the game, the project and/or its infrastructure. As substantial changes will greatly influence the project, they can't be implemented on the fly but need to be fleshed out in detail first, to get a better idea of the pros and cons of these proposals. There are currently four different proposal types, utilized by different development departments: code proposals, feature proposals, tool proposals & infrastructure proposals.

How proposals should work
Proposals are like good wine. We give them some to ripen, to ensure that everyone has the chance to comment on them and that feedback is actually heard. Due the research it takes to write a good proposal, they are actually a good way to minimize the chances of shooting yourself in the foot down the line. Things can still go wrong even after a topic has been explored in detail in a proposal. But a well written proposal does at least ensure that we didn't overlook obvious problems that could cause major problems for us down the line.

How proposals should not work
Proposals shouldn't be used to prove that you're contributing to the project in a substantial way. Don't request proposal review in an aggressive and demanding way.

Feature proposals
Feature proposals are suggestions for features that the PARPG engine should support. These features are usually requested by the other development departments. The programming department evaluates the feature proposals and transforms them into code proposals. The code proposals document how to implement the suggested feature.

Tool proposals
Tool proposals are suggestions for development tools that would improve our asset pipeline. These tool are usually requested by the other development departments. The programming department evaluates the tool proposals and transforms them into code proposals. The code proposals document how to implement the suggested tools.

As a rule of thumb: If you're not contributing to the programming department, write a tool proposal that focuses on the functionality that the tool should provide. If you're a programmer you can write a code proposal right right away. This code proposal should cover both the functionality of a tool and suggestions how implement this functionality.

Infrastructure proposals
Infrastructure proposals are suggestions how to improve the project infrastructure; this also includes the code toolchain and tools for code documentation. Infrastructure proposals will be evaluated by the project management department and implemented down the line if they have been agreed upon.

Department-specific proposals
FIXME

How to write a proposal
All proposals exist as individual wiki pages. To create a new proposal simply enter the corresponding url (e.g. http://wiki.parpg.net/ ) and edit the empty page.

Proposals should be written in a formal manner (i.e. third person view) and use the following template for the different types of proposals:

Feature proposal template
Write a brief description/summary of the proposed feature(s), no more than a paragraph or two. This summary will be displayed above the table of contents.

Rationale
Describe why there features are either essential or would be a huge improvement over the status quo.

Proposed features
List the features what you would like to see supported.

Pros and Cons
Evaluate the various pros and cons associated with implementing the proposed features.

Add sections and subsections as appropriate to help organize and describe the changes and their effects.

Tool proposal template
Write a brief description/summary of the proposed tool, no more than a paragraph or two. This summary will be displayed above the table of contents.

Rationale
Describe why introducing such a tool would be useful for PARPG development.

Tool functionality
Describe what kind of functionality the tool would provide and how it would fit into the existing asset pipeline. This also includes expected input and output parameters and/or file formats.

Pros and Cons
Evaluate the various pros and cons associated with implementing the proposed tool.

Add sections and subsections as appropriate to help organize and describe the changes and their effects.

Infrastructure proposal template
Write a brief description/summary of the proposed infrastructure change, no more than a paragraph or two. This summary will be displayed above the table of contents.

Rationale
Describe why the changes are needed.

Infrastructure functionality
Describe what kind of functionality the new infrastructure would provide. This also includes how this proposed change would affect the rest of the established project infrastructure.

Pros and Cons
Evaluate the various pros and cons associated with implementing the proposed changes.

Add sections and subsections as appropriate to help organize and describe the changes and their effects.

Department-specific proposals
FIXME