Proposal: UPSTREAM.md -- better tracking of upstream code in the JDK

[Dalibor Topic]

On 21.04.2022 22:40, Magnus Ihse Bursie wrote:

> So another way to express this idea is that I'm suggesting we expand on 
> the concept of UPDATING by giving it a standardized name, include it in 
> all imported code, and add some human-and-computer-readable fields at 
> the top that define important characteristic of that code.

I suspect that the updating information may vary considerably from one 
dependency to the next, for example to accommodate the need to apply 
OpenJDK-specific changes or to cherry-pick upstream changes, or to run a 
particular set of external tests, so in order to avoid cluttering the 
file up with things most people not updating a particular component may 
not need to care about, I would suggest following the practice of 
leaving the UPDATING file in proximity of the code of the dependency, 
but defining a common way to reference it in UPSTREAM.md, such

Updating-Instructions: $path

or similar.

> 
>> If each entry in this aggregate UPSTREAM.md file were limited to the 
>> name of the component (not its version), 
> 
> I think it would be a missed opportunity not to include the version number.

Versions are hard, because of modifications that may have been 
performed. For example, a bundled dependency that cherry-picks a handful 
of patches from a future release beside the one it's been based on, may 
be a bit hard to 'version' with a simple upstream number, in particular 
if it e.g. includes additional OpenJDK-specific changes.

The specific versioning information may be better placed in the UPDATING 
file.

I would also suggest adding a

Discussion: $list

field for each dependency, that would point to the corresponding mailing 
list to discuss its source code on. While that would typically be the 
surrounding code's list, it wouldn't necessarily have to be the case in 
case of platform-specific dependencies.

cheers,
dalibor topic

-- 
<http://www.oracle.com> Dalibor Topic
Consulting Product Manager
Phone: +494089091214 <tel:+494089091214>, Mobile: +491737185961
<tel:+491737185961>

Oracle Global Services Germany GmbH
Hauptverwaltung: Riesstr. 25, D-80992 München
Registergericht: Amtsgericht München, HRB 246209
Geschäftsführer: Ralf Herrmann