Clarify contracting process, record and ocid, define planning process (866)

[JachymHercher]

closes #866 (except the two new tickets to be opened on the basis of the last paragraph of #866 (comment))

closes #1159

together with #1208, closes #903

[jpmckinney]

@JachymHercher Is this still draft?

[jpmckinney]

Hi @JachymHercher, this PR now conflicts quite severely with other changes you (and maybe others) made in other PRs. My suggestion would be to:

1. Get a clean version of the 1.2-dev branch, e.g.

    git checkout 1.2-dev
    git pull --rebase
   

2. Start a new branch

3. Look at this PR's changes at https://github.com/open-contracting/standard/pull/1216/files and/or download the PR's changes from https://patch-diff.githubusercontent.com/raw/open-contracting/standard/pull/1216.patch

4. Replicate the desired changes to the new branch. You can perhaps copy-paste the lines starting with + to the new branch, while paying attention to any changes others might have made to those lines.

Would that work? If not, we can perhaps resolve all the conflicts together on a call.

[JachymHercher]

@jpmckinney, thank you for the review. I've gone through your commits and have no major comments. Minor ones:

---

Information about a contracting process or a contracting planning process. Furthermore, a record may also inform about a single stage of a multi-stage procedure (e.g. a framework agreement with reopening of competition).

The reasoning behind this wording was that ocid identifying a "single stage of a multi-stage procedure" is a bit of a hack, so it's included as an "afterthought".

(The existing wording also removes any need for the "minor drafting changes" mentioned at #866 (comment).)

---

In 9943e8b#diff-ad7a21639d13433e0d0f06126a4ce0f979ab8e86ed7f6a28a439df33458419c9, you simplified the note on planning/contracting processes (which looks better now), including the removal of a link to a GitHub issue discussing the matter. Are you sure you don't want to keep the GitHub link? I think the approach of linking "loose ends" in OCDS to GitHub issues is quite nice/useful, but I understand there might also be reasons not to do it.

---

In 257a279#diff-6ab9cecd6acf675b41026bf29c8ed24c2779a9824cc7d09f9ea78b3e73036faf, you removed the following note:

OCID is primarily an identifier for an OCDS contracting process. However, in OCDS 1.2 and earlier, it is also used as an identifier for planning processes and single stages of multiple stage procedures. For a future, backwards incompatible version of the standard introducing a separate identifier for contracting planning processes and publishing data on multiple stage procedures under one OCID is being considered (GitHub issue).

Given the clarification in #866 (comment), I understand why you remove the mention of " introducing a separate identifier for contracting planning processes". However, wouldn't it be useful to keep the note there, even if the sentence only refers to "publishing data on multiple stage procedures under one OCID is being considered "? Same as above, I like highlighthing loose ends, hinting at future developments, showing people where to give their opinion.

[yolile]

@yolile Since this is the most significant clarification/change in 1.2, please also review.

It looks good for me, but should we also update, after merging this, the unsuccessful tender example to have 1 ocid for the planning stage, then another one for the unsuccessful tender, and finally a third one for the successful tender? And, here, for the third ocid, are we going to have two entries in the related process array, one for the unsuccessful tender and another one for the planning stage?

And, should we also update all the other JSON/worked examples where the planning stage is used?

[jpmckinney]

I'll restore the "Furthermore" construction, as mentioned in my recent comments in #866.

In terms of loose ends:

• The challenges/hacks for representing multi-stage procedures in OCDS 1.x is a major issue, so it is important to direct people to an issue where they can contribute (and to demonstrate that we are aware of and working on the issue). I retained the box with the link to Handling multi-stage contracting processes #440 on contracting_planning_processes.md. I'll think about linking to it from identifiers.md (Clarify definition of contracting process #866 is more about our current hack for fixing 440, so I'd rather link to 440).
• Whether to separate planning and contracting processes is one of many decisions that have to be made in OCDS 2.0. Clarify definition of contracting process #866 is not the best place for that discussion, because it is stuck with OCDS 1.1 concerns. It's fine to link to issues about OCDS 1.x in the OCDS 1.x documentation, but since OCDS 2.0 could (in theory) be an entirely different standard, it's less appropriate. We don't want to start conversations about OCDS 2.0 with the baggage/mindset of OCDS 1.x.

I think those are the only two loose ends; both appeared on both contracting_planning_processes.md and identifiers.md.

I have a longer comment about identifying planning processes in #866, but there is no action for now.

[jpmckinney]

@yolile Since this is the most significant clarification/change in 1.2, please also review.

It looks good for me, but should we also update, after merging this, the unsuccessful tender example to have 1 ocid for the planning stage, then another one for the unsuccessful tender, and finally a third one for the successful tender? And, here, for the third ocid, are we going to have two entries in the related process array, one for the unsuccessful tender and another one for the planning stage?

And, should we also update all the other JSON/worked examples where the planning stage is used?

I think we should do all those things. Is it alright, in your opinion, to do those as a high-priority follow-up issue?

For updating the unsuccessful tender example, I think it's fine for the related processes to just be a chain, e.g. the final process only links to the previous attempt, which in turn only links to the planning process. That said, I don't think it's incorrect for the final process to also link to the planning process.

[yolile]

I think we should do all those things. Is it alright, in your opinion, to do those as a high-priority follow-up issue?

Not a high priority, just something we need to remember to do

[jpmckinney]

Follow-up issue is #1362. The problematic commit in my review was 257a279

I have edited ocid. The original in this PR:

A globally unique identifier for this OCDS contracting process. Furthermore, this identifier can also refer to an OCDS planning process or a single stage of a multiple stage procedure.

Now:

A globally unique identifier for the contracting process that the release describes. Alternatively, this identifier can refer to a planning process or a single stage of a multiple stage procedure.

Since this is the release schema, this version more clearly communicates the relationship between a release and contracting process. I also use "Alternatively" instead of "Furthermore" to make clear that these are alternatives: i.e., that a contracting process and planning process are different types of things.

You can read my lengthy commit message for 4abc3af

[jpmckinney]

In the merge commit, I had changed the description of record. The original version in this PR was:

Information about a contracting process or a contracting planning process. Furthermore, a record may also inform about a single stage of a multi-stage procedure (e.g. a framework agreement with reopening of competition).

This unnecessarily replicates semantics that should be deferred to a release. It is now:

A record aggregates releases with the same open contracting process identifier (ocid).

[yolile]

I guess another follow-up is to address this comment: https://github.com/open-contracting/standard/pull/1335/files#r670825255 by updating the planning definition and fields.

[jpmckinney]

I guess another follow-up is to address this comment: https://github.com/open-contracting/standard/pull/1335/files#r670825255 by updating the planning definition and fields.

Thankfully, that PR is still open :)

[jpmckinney]

🚀 🚢