Reordering new API's that have a libctx, propq

[Matt Caswell]

On 14/09/2020 11:30, Matt Caswell wrote:
> In order to try and move this discussion forward I have made a concrete
> proposal for how we should formulate the various ideas in this thread
> into an actual style. Please see here:
> 
> https://github.com/openssl/web/pull/194

I've updated this PR with some of the feedback received so far. Please
take another look.

I plan to start two OTC votes on this tomorrow with the following wording:

"Adopt the coding style policy on function arguments as shown in chapter
6.1 of web PR 194 (commit 7b45b46d71f)"

"Adopt the coding style policy on extending existing functions as shown
in chapter 6.2 of web PR 194 (commit 7b45b46d71f)"

In the event that one vote passes but the other vote does not I will
remove the section of text that did not pass from the PR and adjust
chapter numbers accordingly.

Matt

> 
> Since we're not yet fully in agreement some compromises will have to be
> made. I hope I've come up with something which isn't too abhorrent to
> anyone.
> 
> Please take a look.
> 
> Matt
> 
> 
> On 05/09/2020 04:48, SHANE LONTIS wrote:
>>
>>   PR #12778 reorders all the API’s of the form:
>>
>>
>>   EVP_XX_fetch(libctx, algname, propq) 
>>
>>
>>   So that the algorithm name appears first.. 
>>
>>
>>   e.g: EVP_MD_fetch(digestname, libctx, propq);
>>
>> This now logically reads as 'search for this algorithm using these
>> parameters’.
>>
>> The libctx, propq should always appear together as a pair of parameters.
>> There are only a few places where only the libctx is needed, which means
>> that if there is no propq it is likely to cause a bug in a fetch at some
>> point. 
>>
>> This keeps the API’s more consistent with other existing XXX_with_libctx
>> API’s that put the libctx, propq at the end of the parameter list..
>> The exception to this rule is that callback(s) and their arguments occur
>> after the libctx, propq..
>>
>> e.g:
>> typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_with_libctx_fn)
>>     (const OSSL_STORE_LOADER *loader,
>>      const char *uri, OPENSSL_CTX *libctx, const char *propq,
>>      const UI_METHOD *ui_method, void *ui_data);
>>
>> An otc_hold was put on this.. Do we need to have a formal vote?
>> This really needs to be sorted out soon so the API’s can be locked down
>> for beta.
>>
>> --------
>> Also discussed in a weekly meeting and numerous PR discussions was the
>> removal of the long winded API’s ending with ‘with_libctx’
>> e.g CMS_data_create_with_libctx
>> The proposed renaming for this was to continue with the _ex notation..
>> If there is an existing _ex name then it becomes _ex2, etc.
>> There will most likely be additional parameters in the future for some
>> API’s, so this notation would be more consistent with current API’s.
>> Does this also need a vote?
>>
>> Regards,
>> Shane
>>
>>