added docs for git, versions, and changelog

[mmccarty]

This describes a slightly more conservative approach than what we discussed, but this is taken from the RAPIDS team. I thought perhaps folks on the @nv-legate/core-team would find it more comfortable.

[mmccarty]

Weird. The docs built locally. Thanks @manopapad

[manopapad]

I am generally fine with this workflow, although I would prefer the development branch to have a stable identifier (something like develop). Does anyone have comments on using tags instead / in addition to named branches for releases?

[marcinz]

I wonder how a constant develop tag interacts with PRs. Say that I create a PR vs a current release branch, then this PR will remain against this branch even if a new one is created. If I create a PR against a develop branch, it can accidentally become a sliding target. I think being explicit in targeting PRs to a particular release could be beneficial.

I think using tags for releases has a similar issue. From what I understand, we want to potentially work on a frozen release branch, which means it should remain a branch as it is still "alive."

[mmccarty]

In general, we should avoid PRs against long lived development branches. As long as we are all PRing to the release branch, we avoid the sliding target.

I think being explicit in targeting PRs to a particular release could be beneficial.

Which is the proposal here.

[mmccarty]

As of today, the new-core branch is 44 commits ahead, 5 commits behind nv-legate:master.

If everyone is good with this workflow, I propose we make new-core the release branch in the main repo.

Thoughts?

[lightsighter]

If everyone is good with this workflow, I propose we make new-core the release branch in the main repo. Thoughts?

I think I'm good with this once the new-core is back to functional parity with the existing core. Performance regressions are probably ok and can be worked through, but we shouldn't break anything that we have working right now. @magnatelee to comment as well.

[mmccarty]

Just to clarify: I'm proposing we create a release branch here of new-core that is not frozen, which would mean it is still under active development and can be broken. The dev team could then test, make smaller PRs to that release branch, collaborate, etc. User's would continue to install legate from main until we roll out a frozen release that we have verified.

[lightsighter]

Ok, no arguments from me then.

[magnatelee]

I'm fine with making new-core a release branch. We'll need to do the same for Legate NumPy, as I keep a version consistent with the new core under the same new-core branch in my fork. What's the name of the release branch going to be?

[mmccarty]

That would depend on the target release date. We haven't settled on a cadence so we can pick whatever we want. Since we are using CalVer, we just need to pick a month. For example, if we pick August the branch would be branch-21.08.

[mmccarty]

@marcinz Do you know why the build is failing? The logs just show...

Already up to date.
Error: Process completed with exit code 2.

[marcinz]

@marcinz Do you know why the build is failing? The logs just show...

There were issues with the build script at the time when you branched off. The CI uses the build scripts from the point when you created the branch. There was an issue with how the commit for the pull request was being checked out, and I think this is the issue here. You have two options. You could rebase this branch, and then you'll get the latest version of CI, or you could just merge it and let CI run on the merge.

[marcinz]

Talking about CI, this will complicate CI a bit. Currently, CI in Pandas and Numpy builds against master in legate.core. What would be a reliable way to decide against which legate.core to build in the new setup?

[mmccarty]

No problem. I'll rebase.

[mmccarty]

Anything further here?

[mmccarty]

Talking about CI, this will complicate CI a bit. Currently, CI in Pandas and Numpy builds against master in legate.core. What would be a reliable way to decide against which legate.core to build in the new setup?

@marcinz - Sorry, I missed this. We would need to keep them all on the same release branch. Or we could keep them in the same repo.

[magnatelee]

@mmccarty I'm ready to rename and push the new-core branches. Let's aim at doing a release on August. (so we will go with branch-21.08 as you proposed.)

@marcinz I'm about to move the new-core branches to the main repositories, all under the same name (branch-21.08). Will the CI work correctly for them? Also, is it possible to skip tests when the repository doesn't have the right branch? Legate Pandas is yet to be ported to the new API, so the repository won't have the release branch for a while. (I guess I could push one without any changes, but that would just break right away.)

[manopapad]

I added a note about (mostly) using PRs for making changes.

[mmccarty]

Closing this PR and opening a new on to branch-21.10. We should follow any open discussions here in an issue.