Update all stage object descriptions and release tags

[jpmckinney]

This issue is split from #1160. Copying @JachymHercher's comment (originally at #1160 (comment)):

---

The issue started with awardStatus, moved to [block]Status in general, then we realized that we needed to better define [blocks]. I've started from the back, so below are some observations and a proposal on new definitions for the blocks.

1. I don't think we need a perfectly hard definition, time-wise, of where each stage starts and finishes, because a) each stage is precisely defined by the data fields it contains; b) it's hard to do. Consequently, I do not put the time borders in the first sentence of the description but only later on and introduce them with "Typically".
2. Above, we didn't really address the question of where the planning stage starts and ends (i.e. the tender stage starts). This corresponds to the boundary between a planning and contracting process (i.e. the first "action towards concluding/implementing one or more contracts"). Nor did we discuss where the contract stage / contracting process ends.
   a.) I propose not to define the start of the planning process, because it would necessarily be very fuzzy (e.g. "After the first idea to purchase / fulfill a need.")
   b.) Similarly, I propose not to define the end of the contracting process, because it is not necessary. The implicit approach of "publish as long as it makes sense" might be good enough. (If we wanted to go for it, it is actually a quite tricky question - I would propose "Until the end of any legal obligations stemming from the contract (e.g. maintenance, warranty, options, etc.)")
   c.) For the border between planning/tender, I use "publication of the procurement documents", together with "typically". @jpmckinney in Update all status codelists #1160 (comment) proposed also "reservation of the budget", but I would rather avoid it, as I'm not sure how widely understood "reservation" is (versus proposal, approval and apportionment) and because we only have budget information in the Planning block.
3. I'm also wondering about the difference between the descriptions of the blocks and the same/similar named objects nested within them. For contracts and awards, these correspond to concrete real-world objects and we have separate issues working on their definitions. For planning and tender, I take them as somewhat artificial, and would deal with it by having the descriptions identical for both blocks and objects.
4. eForms allows bid submissions deadlines (equivalent to tenderPeriod) to differ per lot. OCDS currently does not (not even with the lot extensions), but once it does this will interfere with the definition of the tender stage, beacuse it currently assumes that there is a single submission deadline for the entire contracting process. I suggest we deal with it when we get there.

Current block descriptions

planning: "Information from the planning phase of the contracting process. This includes information related to the process of deciding what to contract, when and how.",

tender: "The activities undertaken in order to enter into a contract.",

awards: "Information from the award phase of the contracting process. There can be more than one award per contracting process e.g. because the contract is split among different providers, or because it is a standing offer.",

contracts: "Information from the contract creation phase of the procurement process.",

Proposed descriptions, wording 1

planning, Planning, relaseTag code 'planning': Planning process information about, for example, the rationale for the procurement, the budget, forecasting and market research. Typically, this information comes from actions before the publication of the procurement documents.

tender, Tender, relaseTag code 'tender': Contracting process information about, for example, the items to be purchased, their value, procurement method, award criteria, and various deadlines. Typically, this information comes from actions starting with the publication of the procurement documents and ending with the bid submission deadline. Alternatively, this block is used during the planning process before the procurement documents are published, e.g. to give the market a general description of the purchase or a general estimate of the purchase's value.

awards, relaseTag code 'award': Contracting process information about the award. Typically, this information comes from actions after the bid submission deadline and ending with the award itself or, if there is a standstill period, the end of the standstill period.

contract, relaseTag code 'contract': Contracting process information about the contract and its implementation. Typically, this information comes from actions taken after the award and, if there was a standstill period, after the end of the standstill period.

Proposed descriptions, wording 2

(This wording mentions the type of process later on. While not going "from general information to concrete information", I find it better readable.)

planning, Planning, relaseTag code 'planning': Information about, for example, the rationale for the procurement, the budget, forecasting and market research. This information concerns the planning process and typically comes from actions before the publication of the procurement documents.

tender, Tender, relaseTag code 'tender': Information about, for example, the purchased items, their value, procurement method, award criteria, and various deadlines. This information can concern the contracting process or the planning process. In contracting processes, it typically comes from actions starting with the publication of the procurement documents and ending with the bid submission deadline. In planning processes, it typically comes from actions taken before the procurement documents are published, e.g. to give the market a general description of the purchase or a broad estimate of the purchase's value.

awards, relaseTag code 'award': Information about the award. This information concerns the contracting process and typically comes from actions after the bid submission deadline and ending with the award itself or, if there is a standstill period, the end of the standstill period.

contract, relaseTag code 'contract': Information about the contract and its implementation. This information concerns the contracting process and typically comes from actions taken after the award and, if there was a standstill period, after the end of the standstill period.

---

In my comment above, I've clarified that bid submission falls into the tender stage and not the award stage, as discussed above. Furthermore, I've added alternative wordings and clearer identification of which blocks, fields and codes should change. The comment now covers answers to questions 1-3 in #1160 (comment).

---

Questions 1-3 are copied here:

1. Contract definition covers also unsigned contracts - done.
2. Decide where the tender and award stages end. I think they should end with bid submission and the award decision, respectively.
3. I would suggest: update the definitions of Planning, Tender, Awards and Contracts as well as the corresponding values in https://standard.open-contracting.org/latest/en/schema/codelists/#release-tag so that they take into account the start and end points of each stage and thus avoid overlaps. We can also standardize the wording.

[jpmckinney]

Coping other action items from #1160 (comment)

5. Explain all this in the documentation. Where stages start and finish should probably be part of Getting Started, un-successful procedures part of https://standard.open-contracting.org/latest/en/guidance/map/unsuccessful_tender/.
6. In https://standard.open-contracting.org/latest/en/schema/codelists/#document-type, 'evaluationReports' are classified as belonging into tender, but according to our discussion above they should belong to award. We should change it.
7. Update docs/primer/how.md based on this issue (decided not needed, see below)

[jpmckinney]

I agree with the first 4 points. For point 3, for awards and contracts, the array and object can have different titles/descriptions to match the stage and individual real-world object (award, contract). For planning and tender, the relationship is 1-1 between stage and "object" (if there is such an object - as mentioned, it is somewhat artificial), so it makes sense to simply use the same title/description in both.

I also prefer wording 2, as it starts with familiar concepts, and then introduces "planning process" and "contracting process" which are a bit more OCDS-specific. I've made the following table from the proposal above, which I'll subsequently copy-edit.

Originals	New
planning: Information from the planning process. This includes information related to the process of deciding what to contract, when and how.	Information about, for example, needs identification, budget planning and market research. This information concerns the planning process. This information typically concerns the period before the publication of procurement documents.
Planning: Information from the planning process. Note that many other fields can be filled in a planning release, in the appropriate fields in the tender section; these would likely be estimates at this stage, e.g. value in tender.	As above
'planning' code: A contracting process is proposed or planned. Information in the tender section describes the proposed process. The tender.status field should be used to identify whether the planning is at an early pipeline stage, or whether there are detailed plans for a tender developed.	As above
tender: The activities undertaken in order to enter into a contract.	Information about, for example, the needed items and their estimated value, procurement method, award criteria, and various deadlines. This information concerns either the contracting process or the planning process. For a contracting process, this information typically concerns the period starting with the publication of procurement documents and ending with the bid submission deadline. For a planning process, this information typically concerns the period before the publication of procurement documents.
Tender: Data regarding tender process - publicly inviting prospective contractors to submit bids for evaluation and selecting a winner or winners.	As above
'tender' code: Providing information about a new tender (call for proposals) process. Tender release should contain details of the goods or services being sought.	As above
awards: Information from the award phase of the contracting process. There can be more than one award per contracting process e.g. because the contract is split among different providers, or because it is a standing offer.	Information about the awards. This information concerns the contracting process. This information typically concerns the period after the bid submission deadline and ending with the award or, if there is a standstill period, the end of the standstill period.
'award' code: Providing information about the award of a contract. One or more award sections will be present, and the tender section might be populated with details of the process leading up to the award.	As above
Award: An award for the given procurement. There can be more than one award per contracting process e.g. because the contract is split among different providers, or because it is a standing offer.	(FYI only) See #895 and #1175
contracts: Information from the contract creation and implementation phase of the contracting process.	Information about the contracts and their implementation. This information concerns the contracting process. This information typically concerns the period after the award or, if there was a standstill period, after the end of the standstill period.
'contract' code: Providing information about the details of a contract that has been, or will be, entered into. The tender section might be populated with details of the process leading up to the contract, and the award section might contain details of the award on the basis of which this contract will be concluded.	As above
Contract: Information regarding the contract, typically between the buyer and supplier. This includes contracts describing all the contractual conditions (e.g. item, quantity, price, payment terms, time and place of delivery), as well as contracts only describing the general contractual conditions (such as a framework agreement) and those only describing the specific contractual conditions (such as a contract within a framework agreement). Communication between contractual parties that consists of minor specifications of conditions agreed previously (e.g. specifying the time or place of delivery) is not considered a contract. Amendments are considered as part of the contract that is being amended. Contracts are also used when giving prizes or other rewards (e.g. a follow-up contract) resulting from a design contest.	(FYI only) Resolved in #896 and #1208

[jpmckinney]

@JachymHercher I've made my edits. You can see them using the "edited" dropdown in the previous comment.

A challenge is that OCDS can cover non-procurement contracts, but it is specialized for procurement. I've tried to use non-procurement-specific terms where it didn't introduce awkwardness.

[JachymHercher]

Thank you for the new issue. I've gone through your edits, my comments:
i. My original description of planning as well as the last sentence of tender drew heavily on the description of the planning process, cf. https://github.com/open-contracting/standard/pull/1216/files#diff-ad7a21639d13433e0d0f06126a4ce0f979ab8e86ed7f6a28a439df33458419c9 . Having them aligned might be useful, as they both speak about the same thing?
ii. I agree that "comes from actions" is a bit weird, but the problem with "describes actions" is that a lot of the published information are not actual actions - e.g. award criteria, estimated values, etc.
iii. Isn't "before" better than "prior to", because it's simpler / a more common word?
iv. Just to confirm, in contracts, you prefer "or" to "and", because the "or" can be inclusive, correct?

[jpmckinney]

i. I hadn't considered that alignment. In #1216 the content is:

establishing the rationale for the procurement, giving the market a general description of the purchase, getting the necessary budget, forecasting and conducting market research

For planning, it was:

the rationale for the procurement, the budget, forecasting and market research

then:

needs identification, budget planning and market research

Unless I misunderstand "forecasting", this is not covered by OCDS, so I removed it/changed it to "budget planning". To avoid reference to procurement, I changed to "needs identification".

For tender, it was:

give the market a general description of the purchase or a broad estimate of the purchase's value

then:

draw the market's early attention to potential bid opportunities

I changed it so that it was not specifically about a purchase (e.g. the market can bid on the sale of a state asset). (The latter is based on wording in Australian legislation.) I dropped the second half about estimated value, because I couldn't find wording that worked in a non-purchase context without being overly general, long or confusing, e.g. "the value of the items considered within the contracting process".

We can refine the content further, but I think it is better to update the content added in #1216.

ii. Instead of "it typically describes actions", how about "this information covers the period [before the publication of procurement documents]"?

iii. Yes, changed. We use "prior to" rarely.

iv. I wasn't clear on the intended meaning. My understanding: (1) There is an award, then there is a standstill period. The contracts array covers events that occur after BOTH. (2) There is an award, and no standstill period. The contracts array covers events after the award. What is the desired meaning?

[JachymHercher]

i. planning - your changes sound good.
i. tender - The example's original proposal was concretely about description and value, with the goal of illustrating the use of tender in a planning stage. The new proposal does not do this, it is simply about the planning stage.
      a) can't we speak about items? E.g. "give the market a general description of the items or a broad estimate of their value" or "draw the market's early attention to the items". It's a bit inelegant, but not specific to procurement while explaining the use of tender in the planning stage (the "general" and "broad" are the crucial differences compared to using tender in the tender stage).
      b) Perhaps the use of tender in planning is obvious and we do not need an example? Since its description starts with "needed items and their estimated value", then "general description of the purchase or a broad estimate of the purchase's value" at the end might be unnecessarily repetitive. We do not give an example in the "for a contracting processes" part.
      c) If you wanted to keep the example, I find "market's early attention to potential bid opportunities" quite abstract/complicated - it does sound like coming from some legislation :-). At least, we could replace "potential bid opportunity" with "business opportunity"? I'd argue potential is unnecessary, because every opportunity is potential, and "business opportunity" is more straightforward than "bid opportunity"?

We will need to slightly update the definition of a planning process, I've made a placeholder in #866 (comment).

ii. It's good, still precise and much more natural (the contracting and planning processes to speak about "actions" though, so we lose this link). I'd just leave "typically" there, same as we do for the other descriptions, so "typically covers" instead of "covers".
iv. It's ok the way it is. (Your understanding is correct. My doubt was that if we say "It typically describes actions after the award or, if there was a standstill period, after the end of the standstill period." then reading the or as XOR, this wouldn't be correct, because whatever happens after the standstill period also happened after the award period". However, if we can assume that people understand or as OR and not as XOR, we're fine.)

[jpmckinney]

i. I think b) is the best option.

c) We don't use the word "business" much (not for any principled reason, however), and I think "bid opportunity" is clearer, because it references an action we do write regularly about. I think the reason for "potential" is that a PIN doesn't guarantee that the opportunity will become real (e.g. the buyer decides not to procure anything after all).

ii. OK to re-add "typically"

[JachymHercher]

The PR is ready.

I have also reflected the discussions leading to #1385 (comment) into the overview in #1385 (comment).

Note below that contracts now uses "period" in two meanings. I think it is ok.

contracts: Information about the contracts and their implementation. This information concerns the contracting process. This information typically concerns the period after the award or, if there was a standstill period, after the end of the standstill period.

---

Concerning the two tasks in #1385 (comment),

Explain all this in the documentation. Where stages start and finish should probably be part of Getting Started, un-successful procedures part of https://standard.open-contracting.org/latest/en/guidance/map/unsuccessful_tender/.

I have reviewed https://standard.open-contracting.org/latest/en/primer/how/ and I don't think it needs changing (the descriptions are so general that they fit with also with the new descriptions). I have clarified in #1160 (comment) that we should double-check the documentation also once we are done with #1160.

In https://standard.open-contracting.org/latest/en/schema/codelists/#document-type, 'evaluationReports' are classified as belonging into tender, but according to our discussion above they should belong to award. We should change it.

'evaluationReports' is part of the PR.

The PR also resolves #866 (comment).

[jpmckinney]

Great, and for your action item:

Explain all this in the documentation. Where stages start and finish should probably be part of Getting Started, un-successful procedures part of https://standard.open-contracting.org/latest/en/guidance/map/unsuccessful_tender/.

Is there anything to do?

[JachymHercher]

No. (The reasons were already given in #1385 (comment) but I didn't distinguish sufficiently which comment concerned which task - I've updated it to make it clearer.)