[graalvm-dev] RFC: Changing Mandrel repository's default branch

[Foivos Zakkak]

Hello all,

In the mandrel repo `master` is essentially a mirror of graal's
`master`. The only differences between the two
(https://github.com/oracle/graal/compare/master...graalvm:master) are:

1. An additional readme file (README-Mandrel.md)
2. A header in the original Readme.md pointing to README-Mandrel.md
3. Altered github issue templates
4. Github workflows for syncing `master` with graal's `master` and
testing it, plus some housekeeping of issues

That said, the `master` branch currently serves the following purposes:

1. Welcoming people to the project, informing them about it and
providing issue templates for them (i.e. serving as the landing page).
2. Testing graal's master nightly against upstream OpenJDK (using
Mandrel's build scripts and testing procedure)
3. Housekeeping issues, PRs etc. (i.e. github automation)

I personally feel that the current state is not ideal and I would like
to propose an alternative.


Issues I see with the current approach:

1. When visiting https://github.com/graalvm/mandrel visitors are greeted
with the Readme file of Graal with the additional header:

# Mandrel

## Welcome to the Mandrel project, please see README-Mandrel.md to learn
more.

It's relatively easy for someone to skip over this and struggle to
understand what Mandrel is and how it defers from Graal.
This will also result in following Graal's build instructions instead of
Mandrel's.

Instead I would prefer the landing page to show the content of
README-Mandrel.md with a link (in the same repo) to Graal's readme.
I believe this would make thinks crystal clear.

2. When cloning with `git clone https://github.com/graalvm/mandrel` one
gets the `master` branch which is unstable in Mandrel and not that
interesting since the Mandrel team is working on the latest release
branch (currently mandrel/20.1) instead.


Proposals:

1. Make the default branch contain only a README file explaining what
Mandrel is, how it relates to Graal, and how to get your hands on it.
This branch will also contain any workflows related to housekeeping,
syncing branches, nightly testing, etc.
This branch will not contain any code. So after `git clone
https://github.com/graalvm/mandrel` and reading the README users will be
asked to checkout another branch if they want to access the source code.
This approach might not be addressing issue 2 sufficiently.

2. Make the latest release branch (i.e. the one being actively
developed, which currently is mandrel/20.1) the default branch.
This will be similar to the current state with the difference that `git
clone https://github.com/graalvm/mandrel` will return something useful.
This approach does not address issue 1 though. So it might need to be
combined with swapping README-Mandrel.md and README.md (i.e. make
README.md contain Mandrel info and point to a README-Graal.md)

I personally prefer the first proposal.

What are your thoughts?
Are there any objections on any of these? Or alternatives you would like
to propose?

Thanks,
Foivos

PS: This is being tracked in https://github.com/graalvm/mandrel/issues/51


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
Url : http://oss.oracle.com/pipermail/graalvm-dev/attachments/20200717/e76947e1/attachment.bin