Feature contracing process and planning process definitions in the reference documentation

[duncandewhurst]

Presently, the following definitions from the description field of the release schema only appear in the implementation guidance:

Contracting process
All the actions aimed at implementing one or more contracts. This covers tendering, awarding, contracting and implementation. It does not include actions linked to planning, as these are often less structured and may be linked to multiple contracting processes. In multi-stage procedures (e.g. framework agreements with reopening of competition), each round of competition is treated as a separate contracting process.

Procedures that failed and were restarted are considered new processes.

Boundaries between processes (e.g. whether two contracts result from a single process or from two processes) are set by buyers depending on their needs (e.g. efficient division of labor, clear communication with the market) and legislation (e.g. rules on using procedures and lots).

Planning process
All the actions aimed at planning one or more contracting processes. This covers, for example, need identification, budget planning, and market research.

Planning processes are often less structured than contracting processes, so one or more planning processes may lead to one or more contracting processes.

The page on which they appear (docs/guidance/map/contracting_planning_processes.md) is only expected to be (optionally) read during the mapping phase of an OCDS implementation, but I think it would aid understanding if these definitions were featured prominently in the reference documentation. The primer does include a definition of a contracting process, but I think this kind of detail more properly belongs in the reference section, since it is something that implementers might need to refer back to when thinking about different kinds of contracting process.

[jpmckinney]

Good idea!

[duncandewhurst]

Looking at it again, I think that most of the rest of the content on the worked example page is pretty fundamental to understanding OCDS. Presently, that page is only linked from the list of 'hard cases' in the mapping guidance and from the related process codelist reference. To increase the chances of readers seeing it and to reduce repetition, I think it would make sense to retire the worked example page altogether and instead integrate the content into the schema and reference documentation as follows:

Worked example content	Actions
"A planning process ought to have its releaseTag set to 'planning' (or 'planningUpdate'). A contracting process can have releaseTag set to any other value from the codelist. A planning process should not contain the releaseTag 'tender' even if it contains a tender object."	Update the description of tag as follows (changes in bold) "A tag labeling the release, using the the open releaseTag codelist. Tags distinguish, for example, planning and contracting processes and the stages of contracting processes. Codes outside the releaseTag codelist might indicate, for example, the notice or form to which the release corresponds, or the event that triggered the publication of the release. Planning processes should use the 'planning' or 'planningUpdate' codes. Contracting processes should use any other value from the codelist. Planning processes must not use the 'tender' code, even if they use tender fields.
"The two processes ought to be linked together using the relatedProcesses array in the releases for the contracting process, with the 'planning' code in the related process' relationship array."	Add "Planning and contracting processes should be linked using the relatedProcesses array." immediately below the contracting and planning process definitions on the reference page and link to the RelatedProcess reference. Update the related process reference to explain that contracting processes should be linked to planning processes using the 'planning' code (the related process reference needs to be rewritten anyway - see #1713).
Note: "We recommend publishing data about planning and contracting processes under separate ocids, following the definitions above. That said, publications that combine planning and contracting data under a single ocid remain conformant in OCDS 1.2. A required separation can be considered for OCDS 2.0."	Move below the planning and contracting process definitions on the reference page.
Note: "In OCDS 1.2 and earlier, it is not possible to publish all information about multi-stage procedures under a single ocid. There is guidance on how to deal with this for framework agreements and for pre-qualification and pre-selection. If you want to disclose this type of information (including other types of multi-stage procedures, such as competitive dialogues and innovation partnerships), contact the Data Support Team. The approach to modelling multi-stage procedures in a future, backwards-incompatible version of the standard is under discussion on GitHub."	Move below the planning and contracting process definitions on the reference page.

@jpmckinney does that sound good?

---

If we decide to keep the worked example, we should fix the erroneous code formatting on releaseTag.

[jpmckinney]

For the bold changes, the singular like in the original is preferred, as a tag is only ever about one process.

I think we can upgrade this to must (since a planning process is, by definition, a process with one of the planning tags and none of the others), and draw out the real intention of the pre-existing last sentence: "A planning process must use either the 'planning' or 'planningUpdate' code, and must not use any other code from the releaseTag codelist."

And we can draw out the real intention of the contracting process phrase: "A contracting process should not use the 'planning' or 'planningUpdate' codes."

We should correct "releaseTag" to "tag field".

Also, the language of "set to 'planning'" is incorrect, since the field is an array not a string.

Let's also fix the "the the" repetition in the tag description.

Other changes sound good.

Edit: Ideally, the shoulds would be musts, but that would mean existing data fails structural checks.

[odscjen]

Just to double check, from your suggestions in #1714 (comment) @jpmckinney we're keeping https://standard.open-contracting.org/staging/1.2-dev/en/guidance/map/contracting_planning_processes/ as a worked example as well as making the changes to the schema and reference page?

[jpmckinney]

I think we can eliminate the worked example. My understanding is that essentially all content will have been copied/adapted into the reference section.

[jpmckinney]

That guidance was introduced in e6bc88b as part of #1216, to resolve #1159 (which was guidance that mixed up the definition of contracting processes with a discussion of unsuccessful processes). In other words, I don't think there was a strong motivation for this content to be under guidance – it was more that it shouldn't be mixed into the unsuccessful process guidance.