Editing Proposal process

<translate>

This page describes the '''proposal process''', which is one of multiple ways to introduce and discuss '''new [[tags]]''' for features and properties. The [[#Non proposed features|other ways]] are often undocumented. The proposal process was designed to as mechanism to document that a rough consensus exists within the community on how to model and tag a feature that previously had no established tagging. The open voting process acts as supporting evidence that the proposal author has adequately reflected feedback from interested parties and meaningfully addressed objections posed.  The outcome of a proposal vote is a change in documentation on the wiki.

As a documentation change, an approved proposal is not binding on any mapper, software developer, or data consumer.  However, tagging backed by an approved proposal is usually regarded as having survived a level of community vetting and scrutiny, and thus carries more weight when compared to alternative methods of mapping a feature. OpenStreetMap does not restrict mapping to tagging schemes backed by an approved proposal -- you can still use [[any tags you like]]. Nonetheless, there is benefit to mappers and data consumers alike in agreeing on a common data model and corresponding tags by reducing conflict between mappers, edit wars, and tagging disputes.

As a non-binding documentation change, '''the outcome of a proposal vote does not compel a change in tools which use and generate OSM data''', such as the [[standard tile layer]] renderings or [[editor]] [[preset]]s.  An approved proposal will not be automatically rendered or added to presets; this is at the discretion of the developers and maintainers of those tools. Also, a vote result is '''never''' permission for large-scale re-tagging of existing objects. See [[automated Edits code of conduct]] for more about this topic.

This page is designed to assist anyone considering putting forward a tag [[proposal]], with the aim of speeding the tag proposing process. Like the proposal process itself, it attempts to describe the rough consensus that has accumulated over the years over the best ways to assess and document community consensus on mapping and tagging. It is not a set of absolute rules, but rather a helpful guide for community members.

All proposals are categorised by the status set in its [[Template:Proposal Page|Proposal Page template]]:

{{:Proposals/cats}}

=== Does it already exist? ===

#Search for possible documentation on this Wiki. <br />For example:

#It might also be a good idea to send an email to the [https://lists.openstreetmap.org/listinfo/tagging tagging mailing list], describe the feature you want to tag and see if there are tags in use but hard to find or not yet documented.

Is the tag you are considering for proposal, worthy of a new tag? Consider possible uses for the map, and specifically the data you want to add.

This is a difficult judgement to make: if you want to tag it, then that is generally reason enough to create a tag.

* Is it a destination in itself?

** People may search for some locations, for example: a national park, a bus station, a street address or a rubbish dump, because they want to visit that location.

** Walkers would want to know surfaces/conditions of walking tracks.

OpenStreetMap has some established [[good practice]]s. Your proposal should follow those or at least explain why it does not do it. Please have a look at them.  

Specifically relevant for proposals might be

; [[Verifiability]]

: There are some conventions about naming [[key]]s and values. Following them will help mappers to estimate the meaning of your tags without reading the documentation. Using a [[Semi-colon value separator| semicolon]] should be considered especially carefully.  

Skimming though [[Editing Standards and Conventions]] might be helpful as well. Please also consider the [[Good_practice#Map_what.27s_on_the_ground|On the Ground Principle]] (about current versus old data), {{key|fixme}} (for estimations), and [[names]] (names versus descriptions, avoiding abbreviations) if any of them might conflict with your ideas.

Your proposal is more likely to be accepted by the community if you take steps to research and vet your proposal before presenting it in front of a global audience.  Some tips for success include:

* Research whether tagging for this feature (or similar) has been discussed before, by searching the [[Mailing_lists#Search_the_mailing_lists|mailing lists]] or other forums.  Consider what objections or concerns were raised in those discussions, and adjust your proposal if necessary to satisfy the concerns.  It may not be possible to please everyone, but you will have the best chance of success if you make the effort to address as many concerns as possible.  Provide links to these discussions in the "External Discussions" section; it shows that you have done your homework and are aware of past discussions that may have occurred.

* Assume that the reader is not an expert in the topic or in the associated tagging.  Give a brief introduction suitable for non-experts that allows them to understand the feature being described, the state of existing (inadequate) tagging, and how your proposal fills that gap.  Do not assume prior knowledge, especially when proposing additions or changes to complex tagging schemes.

You can easily create a pre-formatted proposal here.

'''Read these instructions ''before'' creating the page.'''  

# Create the page using the tool below. The tool does not ''immediately'' create the page, but opens the editor for the page that will be created if saved.  

# Making no edits, '''immediately''' save to convert the substituted values to text. <br>[[File:Save proposal first.png|border|frameless|761x761px]]

# Follow the instructions in the comments under each of the headings to draft the proposal documentation.

'''Create here:'''

<div style="float:left;">

</div>{{Clear}}

If you edit using the Wikicode editor instead of the Visual Editor, what is displayed will be a bit different. Instructions still apply: (1) create page (2) save to generate text, (3) edit page to fill the template and save again.

If you have technical trouble with creating a proposal page, feel free to ask for help by sending a message to the [https://lists.openstreetmap.org/listinfo/tagging tagging mailing list], you can ask for technical help also elsewhere.

Optionally let people know of your new proposal by [https://lists.openstreetmap.org/listinfo/tagging subscribing to tagging mailing list] and [mailto:tagging@openstreetmap.org sending a mail].

You may also create a proposal directly by copying and pasting into a new page

Create a new wiki page such as ''Proposed_features/your_proposition_name'' ([https://www.mediawiki.org/wiki/Help:Starting_a_new_page MediaWiki Help:Starting a new page]) and then fill in the proposal page template and page details described below. Set the status to <code>Draft</code> and set the <code>draftStartDate={{#time: Y-m-d}}</code> value (YYYY-MM-DD):

''Place the following wiki text at the top of the page, and fill in the brief summary content fields:'' (See also: {{t|Proposal_Page}})

<syntaxhighlight lang="moin">

}}

<!-- A short statement of what you propose, including a list of what tag(s) are being proposed to be added, changed, or deprecated -->

<!-- Which Database Elements (nodes, ways, areas, relations) each of the tags can be used on could be included here or under the Tagging heading, or both. -->

<!-- Explanation of why the proposal is needed, and why you chose the specific key and value of the tag. Compare with similar tags or previous proposals, if relevant. Consider significance and potential uses of the data.-->

<!-- Keep the tag short while still being logical and descriptive enough to need little explanation. Avoid tag names which might cause confusion with a  different tag. British English terms are preferred, when possible -->

<!--  

A table, list, or set of subheadings explaining each tag:

-->

<!-- Examples of what elements should be tagged: real-world images, openstreetmap.org screenshots, links to OpenStreetMap elements that use the proposed tagging. -->

<!-- Optional rendering suggestion, if relevant -->

<!-- List of wiki pages that would be edited if the proposal is approved -->

<!-- Links to mailing lists, other forums where this proposal has been discussed... -->

<!-- There must be at least 2 weeks set aside for comment on the proposal. Do not go to a vote without addressing the comments and fixing any problems with the proposal. The wiki talk page is used for comments, it is linked from the proposal page for those unfamiliar with wikis. -->

Please comment on the [[{{TALKPAGENAME}}|discussion page]].

</syntaxhighlight>

Once the proposal contents are fully described, you can propose it to the community.

=== Propose ===

# Consider sending your proposal to some additional [[contact channels]] to further increase community feedback and knowledge of it (not everyone subscribes to the tagging mailing list).

Look through comments that arise from the mailing lists, chats, and the proposal Wiki Talk page.  

When a discussion in a section created by another user on the proposal's Talk page is considered "resolved", you can add the [[Template:Resolved|<code><nowiki>{{Resolved|1=message}}</nowiki></code>]] Template directly below the section heading with an included message.

Adjust, even if it means changing key parts or tags, and continue to build a strong proposal according to community feedback so that it has a good chance of passage once voted on.

Note that it is not necessary to implement all suggestion and requests. While many will be useful, it is possible to receive recommendations contradictory with each other, some can be also misguided.

If there are many changes to the proposal, it may be a good idea to document them in a timeline in a separate section called <code>Changes</code> for reference.

''You still have to be subscribed to the Tagging mailing list for these steps.''

Make sure these your proposal meets these requirements before initiating voting.

* At least two weeks have passed since start of a RFC.

* The proposal is in its final state. It '''cannot''' be changed once voting starts.

# Set these parameters in the [[Template:Proposal page|<code>Proposal page</code>]] template at the top of the page:

## <code>|status = Voting</code>  

<syntaxhighlight lang="moin">

{{Proposed feature voting}}

<!-- Cheat sheet:

{{vote|yes}} OPTIONAL MESSAGE HERE --~~~~

{{vote|abstain}} YOUR COMMENTS HERE --~~~~

Place your vote below, at the end of the list. -->

</syntaxhighlight>

# [mailto:tagging@openstreetmap.org?subject=Feature%20Proposal%20-%20Voting%20-%20%3CFEATURE%20NAME%3E&body=Voting%20has%20started%20for%20%3CPROPOSAL%20NAME%3E.%0D%0A%0D%0A%3CLINK%20TO%20PROPOSAL%20ON%20WIKI%3E Send (mailto link)] a notice that voting has started to the Tagging mailing list.<br>''Or copy:''

## To: <code>tagging{{@}}openstreetmap.org</code>

# Consider posting a notice for voting on some of the other [[contact channels]] as well.

Make sure these requirements are met during voting.

* The proposal is never changed.

* A list of active votes can be found at [[:Category:Proposals with "Voting" status]].

* If you have no time to do the cleanup after the voting has ended:

: Mark the proposal status as <code>status=Post-Vote</code>.  

: (See [[:Category:Proposals without post-vote cleanup]] for features needing clean-up. If you have a minute, pick up a broom and clean up!)

* After the voting period, make a summary of the voting by filling out the parameters of the {{T|Proposed feature voting}} template:

<syntaxhighlight lang="moin">

</syntaxhighlight>

* It is a good idea to [mailto:tagging@openstreetmap.org send] out an update to the tagging mailing list:  

** <Subject:> "Feature Proposal - Approved - (Feature Name)"

** <Subject:> "Feature Proposal - Rejected - (Feature Name)"

If the proposal has found enough support, the status can be set to <code>Approved</code> (both in result parameter in {{T|Proposed feature voting}} and in status parameter of {{T|Proposal Page}} at top of the page).

:Old version applying to proposal votes started before 2021-03-10: A rule of thumb for "enough support" is ''at least 8 approval votes and at least 75 % approval'', (a simple way of counting is that a minimum of 3 yes votes for every no vote is sufficient), but other factors may also be considered (such as whether a feature is already in use).

:[[Proposed features/change vote counting rules - remove dead rule|New version applying to proposal votes started on 2021-03-10 or later]]: "Enough support" is at least 8 approval votes and at least 75 % approval. A simple way of counting is that a minimum of 3 yes votes for every no vote is sufficient.

: The explicit abstentions do not count as a vote (e.g. 10 vote "yes", 1 vote "no", 10 "abstain but have comments" would be approved), but all suggestions should be taken into account before a proposal is approved or rejected in order to resolve any deficiencies in the original proposal (if they exist).

: Before you decide to reject a proposal because of lack of support, it may be worthwhile to [mailto:tagging@openstreetmap.org send] out a new vote request to the mailing list.

See [[/historic notes]] for list of substantial changes in the past. Older proposals are still considered "approved" if they met the standard in place at the time.

Clean up the proposal:

* Do not move the proposal page!

** Do '''not''' remove entries from [[Map Features]] even if your new feature that has been voted on is intended to replace them. It is not considered good style to remove things from Map Features while they are still in use. You can remove things from Map Features if they are not in a significant use. See also [[Deprecated features]].

If the vote fails, do not despair. Many proposals were rejected, modified and succeeded. Sometimes proposal fail because some people noticed issues during vote.  

* The status should be set to <code>Rejected</code>.

* Note any reasons why rejected on the feature proposal page.

* Rejected features may be resubmitted, modified, and new vote started. You can also move back to the RFC process, or at least send some message to give chance of feedback without voting against.

* Proposals should be set to <code>Abandoned</code> if they have a long time of inactivity (at least 3 months) on the wiki pages (including all languages and discussion pages) and are also not added to the OSM database. A proposal that's unchanged in the wiki for a while might just be tested in daily mapping practice and thus may be very alive.  

* The person proposing a feature can cancel it by setting the status to <code>Canceled</code>.

* For proposals with unknown status, set the status to <code>Undefined</code>.

{{anchor|archiving proposals}}<!-- used in WikiProject Cleanup#Historical content -->

Note that abandoned/inactive proposal may be for tag that is in active use. In such case [[creating a tag page]], applying {{T|Archived proposal}} on the proposal page and hiding proposal text may be the best solution. It keeps history available but users are directed to the active documentation.

See [[Proposed features/street vendor=yes]] and [[Proposed features/scaled down streets that may be used for traffic safety education or as a type of a playground|traffic park one]] for examples where it was used.

Non-proposed features are mapping features which did not undergo the proposal process.  

Even if OSM has a completely [[Any tags you like|free data model]] (that is, you don't need anyone's permission), we try to moderate the [[Map features]] list for several reasons:

* landing page for newbies: so it has to be clear and self-explanatory in every language

* keep list/categories short: even a design decision, we want to avoid an uncontrolled explosion of features and keys

Generally, new [[keys]] should always be discussed before being added to [[Map features]]. To increase participation in discussion, especially for new values of major keys like {{key|highway}} it is a good idea to formally propose them. Any new tag which replaces an established tag also requires a proper discussion, proposal process is a good way to achieve this.

There are many old proposals that never reached vote stage and where the original authors have abandoned them. What can be done by a new unrelated person interested in making identical or a similar proposal?

* restart the old proposal - it is a good idea if you completely agree with it. Consider contacting the original author whenever it is OK for you to resurrect it - and wait some time for reply. Send it again to request for comment (RFC) stage and continue to proceed like with any other proposal.  

* make a new proposal reusing content from the old one. Simply create a new page, feel free to copy existing content (you are allowed to do this, just mention source of text in the changeset comment). Mention inspiration/source of the proposal, but feel free to make any changes to it that you want. And proceed like with any new proposal. You can also do this with your own proposals.

* [[Proposed features/man made=bridge]] is case of a simple reviving - person who started vote fully agreed with the original author, proposal was not modified

* [[Proposed features/scuba diving2]] was based on a previously proposed but not finalised [[Proposed features/scuba diving]], proposals were made by different people

* [https://wiki.openstreetmap.org/w/index.php?oldid=1206637 healthcare=blood_donation proposal] was based on the earlier proposal made by the same person that was rejected

You can find the history for this page [{{fullurl:{{FULLPAGENAME}}|action=history}} there] (as usual).

* <code><span style="background:#EEE">[[:Category:Proposals with "Draft" status|draft]]</span></code>: the proposal is in the initial starting period of writing down corresponding information

* <code><span style="background:#EEE">[[:Category:Proposals with "Proposed" status|proposed]]</span></code>: the proposal contents is fully described and it is proposed to the community

* <code><span style="background:#EEE">[[:Category:Proposals with undefined or invalid status|undefined]]</span></code>: the proposal has unknown status

''See also:'' [[Tag_status#Status_values|Tag status values]]

* [[:Category:Proposals by status|Lists of proposals by status]]

* [[User:Joto/How to invent tags]]

* [[Creating a page describing key or value]]