How to work with proposals

From Post-Apocalyptic RPG wiki

Jump to: navigation, search

Lead developer.png This article covers lead developer information!

Lead developer articles are primarily relevant for the lead developers on the team. They either contain high level information about the development process or are meta workflows that aren't department-specific itself but are utilized to derive department-specific workflows from them.

This article describes the rationale for writing proposals, provides some guidelines on how to write them, and elaborates on the different proposal types. This article is mainly relevant to lead developers in the different departments. It provides a generic workflow for writing proposals. The lead developers of the different departments can use this article as starting point for department-specific workflows.

Contents

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. While some types of proposals are specific to certain development departments, there are also general proposal types that are utilized by every department.

How proposals should work

Proposals are like good wine. We give them some time 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 issues for us later on.

How proposals should not work

Proposals shouldn't be used to prove that you're contributing to the project in a substantial way in the shortest possible amount of time. Don't request proposal review in an aggressive and demanding way.

A little secret about PARPG development

But don't tell anyone: pretty much everything (substantial) in PARPG starts out as a proposal. The departments use different names for proposals, either to underline their purpose (code proposals) or to mask their proposal nature to make them sound less scary (game mechanics, writing content).

But the truth is, all proposals are similar in these regards:

  • It takes substantial work/thought/research to write a good proposal
  • They're a good way to avoid shooting ourselves in the foot down the line by actually thinking things through
  • There are guidelines how to write these proposals
  • There is a review process to determine the level of maturity of a proposal and to have an overview which proposals are already agreed upon or even implemented

How to flesh out a proposal

Whenever you flesh out a new proposal - regardless of the specific field of work - there are two different ways to approach this. In reality most developers will neither write pure organic proposals nor pure power plant proposals. But it helps to define these two cliché proposal types to get across the point how proposal writing should be approached.

Organic proposals

Organic proposals are often based on brainstorming sessions at the IRC channel or the forum. Whenever brainstorming sessions lead to something worth exploring in more detail, a new stub proposal is created at the wiki. A stub proposal just needs two kinds of information at the beginning:

Categorization of the proposal
What kind of proposal is it? Feature proposal, tool proposal, infrastructure proposal? Or a department-specific one, e.g. a game mechanic or writing content?
A summary/description
Every stub proposal should have a spot on summary that describes what the proposal is all about. If you can't come up with a reasonable summary for the proposal, it's prolly not ready for the wiki and needs some more brainstorming/feeedback. This summary is regularly updated as the proposal evolves.

Once you have a stub proposal, all interested developers can contribute to fleshing it out. By getting feedback from the other devs early, we can pretty much guarantee that we're running in the right direction with it. Organic proposals get fleshed out over a longer period of time and grow organically, based on the feedback and the contributions of all interested developers. As organic proposals are not meant to be implemented in the shortest possible amount of time, every developer actually has the chance to have his/her feedback heard. This is how proposal writing should be approached in the vast majority of the cases.

Power plant proposals

Power plant proposals are pretty much the contrary of organic proposals in several regards. Power plant proposals are often not based on brainstorming with other developers but are brought up by a single developer. Power plant proposals don't grow organically and feedback by others is not incorporated while the proposal gets fleshed out. These proposals are often fleshed out in a very short amount of time and are quite massive: they're either very lengthy and/or the proposal will influence the development of the game and/or the project in a major way. As power plant proposals don't incorporate feedback while they get fleshed out, the review process should not be rushed. Writing a power plant proposal and demanding immediate proposal review in an aggressive way is pretty much a guarantee that the proposal will be initially rejected. That's why power plant proposals should be avoided: they don't incorporate feedback, they pressure the other developers and they're actually not like good wine - they often don't get the necessary time to ripen.

General proposal types

Besides the department-specific types, there are also proposals that are not specific to any department and can be written by everyone in the community. They are used to propose new features, suggest tools to improve our asset pipeline or to introduce changes to the project (infra)structure.

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 kind of tools 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 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 (infra)structure; 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.

As a rule of thumb: if a proposal affects several departments, chances are good that it should be an infrastructure proposal. Also: if a proposal doesn't cover a suggested feature nor a tool (and isn't any department-specific proposal type either), it should be an infrastructure proposal.

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/<proposal_name>) and edit the empty page.

Proposals should be written in a formal manner (i.e. third person view) and use the following templates as starting point for the different types of proposals. Apply your best judgement and include all information that seems relevant to the proposal to you.

General proposal types

Feature proposal template

{{Feature proposal}}
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

{{Tool proposal}}
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

{{Infrastructure proposal}}
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

Department specific proposals - even if they proposal nature is masked with a clever and less scary name - follow different guidelines. Check out the starting pages of the different departments for more information how the specific departments approach the proposal writing process. Just to give you two examples how this could work in different fields:

  1. Programming department: Code design workflow
  2. Game design department: Game mechanics design process

Proposal review process

While the proposals get fleshed out, developers and community members provide constant feedback to help you to write a great proposal. Proposal review slightly varies from department to department. The general proposal types (feature, tool & infrastructure proposals) are not strictly categorized according to their status. If you feel like your general proposal is ready for review, let the developers know about it at the forums and/or the IRC channel. For details, see #Type III proposals

Department-specific proposals are categorized according to their status in a more strict and formal way. As a rule of thumb: a department-specific proposal has the status work in progress while it gets fleshed out. Once it has been fleshed out in detail, it gets tagged as submitted to inform the other developers on the team that it's ready for review. Beyond that, there are two common ways of categorizing proposals based on their level of maturity. You don't have to worry about it when writing your first proposal. The other developers fill you in about the details and the difference between the two types just matters very far down the line in the review process.

The difference between Type I and Type II proposals is subtle. But in case you're still interested in the details, there you go.

Type I proposals

In a nutshell: Type I proposals can be actually implemented. E.g. a tool for the asset pipeline would be a Type I proposal as you would have a piece of software that can be run after the proposal was implemented.

The status of Type I proposals is categorized in this way, based on their level of maturity:

  1. Work in progess: these proposals still get fleshed out (or might be even just stubs) and are not ready for a full featured review by the other developers.
  2. Submitted: these proposals have been fleshed out in detail and feedback by developers and community members has been incorporated. They're now ready for a review by the other developers.
  3. Accepted: these proposals have been reviewed and review process feedback has been incorporated. They have been agreed upon and are now awaiting implementation.
  4. Implemented: these proposals have been already implemented. They reside at the wiki as documentation of implementation details.
  5. Deprecated: these proposals are not being actively worked on anymore. This status also applies to formerly accepted or implemented proposals that are now superseded by a new proposal.

Type II proposals

In a nutshell: Type II proposals can't be implemented directly. Once they have been agreed upon, they serve as guidelines for the development of PARPG.

The status of Type II proposals is categorized in this way, based on their level of maturity:

  1. Work in progess: see Type I.
  2. Submitted: see Type I.
  3. Established: these proposals have been reviewed and review process feedback has been incorporated. They have been agreed upon and are serve as guidelines for development.
  4. Deprecated: these proposals are not being actively worked on anymore. This status also applies to formerly established proposals that are now superseded by a new proposal.

Type III proposals

In a nutshell: Type III proposals aren't categorized based on their level of maturity. Type III proposals are considered up-to-date but constantly evolving. Here are some examples of (masked) Type III proposals:

  • Feature, Tool & Infrastructure proposals
  • Wiki editing guidelines
  • Coding standards of the programming department
  • Writing content guidelines of the writing department
Personal tools