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

[Magnus Ihse Bursie]

On 2022-04-22 03:06, Jonathan Gibbons wrote:
> Putting these markdown files amongst the *.java and other kinds of 
> source files seems wrong.

The idea originated with the concept of having a "marker" file, saying 
that "this directory is from external sources". Several such directories 
already have a file like README or UPDATING.txt that contains 
information about the external sources, just not in a standardized 
manner. With the marker file co-located with the sources, listing all 
external sources in the JDK is as simple as a "find . -name UPSTREAM.md".

> I like the idea of a standardized file in a standard place, but maybe 
> it would be better per-module, in `src/<module>/UPSTREAM.md` and 
> contain a relative path to the root of the upstream files in that 
> module. All with suitable accommodation when a module has multiple 
> upstream components. Variants might be 
> `src/<module>/UPSTREAM-<component>.md` or 
> `src/<module>/upstream/<component>.md`.

Don't think you can trick me into suggesting yet another directory under 
the $MODULE hierarchy. ;-) That'll trigger a debate with no end.

In fact, we have no precedence of putting any files at the src/$MODULE 
level, so even that would probably raise some eyebrows. (And also, I 
think, give unwarranted exposure to a file that is only really relevant 
if you are actually looking at the 3rd party code in question, not every 
time you cd into a module directory.)

/Magnus

>
> -- Jon
>
> On 4/21/22 11:58 AM, Magnus Ihse Bursie wrote:
>>
>> My suggestion is that we add a file, UPSTREAM.md, in the top 
>> directory of the imported 3rd party code. These files will follow a 
>> pattern, with a set of formalized headers on the top, a blank line of 
>> separation, and then a free-form markdown text, with e.g. relevant 
>> notes about the project, important information about the latest 
>> update, or instructions or hints on how to update the source to a 
>> newer version.