search

cloudfoundry / diego-release

BOSH Release for Diego
Apache License 2.0
201 stars 212 forks source link

it should be easier to discover what version of diego-release is compatible with my cf-release deployment #56

Closed shalako closed 9 years ago

shalako commented 9 years ago

I have deployed cf-release. Which version of Diego do I choose?

Two use cases:

Stable Given a final release of cf-release, what final release of diego-release do I deploy, and how do I generate a compatible manifest? Note: instructions should not involve looking up shas. Desired workflow:

  1. Deploy cf-release final release
  2. Following documentation on diego-release README, discover latest compatible final release of diego-release
  3. Upload diego final release, create manifest, and deploy
bosh upload release releases/diego-0.1319.yml
git checkout v0.1319
./bosh-lite/make-manifest
bosh deploy

This may require tagging. [#55]

Edge I'm deploying release candidates. Given a sha of cf-release, what sha of diego-release should I checkout to create a release and manifest from? Desired workflow:

  1. Deploy cf-release from release-candidate
  2. Following documentation on diego-release README, look up latest compatible version of diego-release for sha of cf-release
  3. Upload release, create manifest, and deploy
git checkout 4137e31
bosh create release
bosh upload release
./bosh-lite/make-manifest
bosh deploy
cf-gitbot commented 9 years ago

We have created an issue in Pivotal Tracker to manage this. You can view the current status of your issue at: https://www.pivotaltracker.com/story/show/97867540.

amitkgupta commented 9 years ago

Hey @shalako, you might want to look at: https://github.com/cloudfoundry-incubator/diego-cf-compatibility.

shalako commented 9 years ago
  1. The matrix is not discoverable. It would help to link to it from the diego-release README, which should be considered the front door for everything Diego. I recommend referring to it in the instructions for deploying Diego to bosh-lite, as well as at the top very top of the README where dependencies are discussed.
  2. The matrix doesn't mention final releases of cf-release.
amitkgupta commented 9 years ago

It's perhaps unconventional, but https://github.com/cloudfoundry-incubator/diego is the front door. It's discoverable from there.

The spreadsheet doesn't mention final releases because the team responsible for cf-release doesn't cut final releases. Currently a commercial team handles that responsibility, and it's outside of the usual CI pipelines. In the coming weeks we will be spinning up a team to make the CI and release processes more unified and more OSS-user-friendly.

On Friday, June 26, 2015, Shannon Coen notifications@github.com wrote:

  1. the repo is not discoverable. It would help to link to it from the diego-release README, which should be considered the front door for everything Diego. I recommend referring to it in the instructions for deploying Diego to bosh-lite, as well as at the top very top of the README where dependencies are discussed.
  2. The matrix doesn't mention final releases of cf-release.

— Reply to this email directly or view it on GitHub https://github.com/cloudfoundry-incubator/diego-release/issues/56#issuecomment-115767418 .

shalako commented 9 years ago

Yeah, that is unconventional. I never would have known to look there. Your front door is where people try to get in, not where the door is built. It might be interesting to compare visit metrics between the diego and diego-release repos.

So how is this repo that doesn't appear to serve any purpose but link aggregation discoverable? The release repo doesn't point there, but it does point to another repo for design docs.

I would argue that everything on the diego repo README belongs instead on the diego-release README.

amitkgupta commented 9 years ago

Fair points. It's hard to say where people unfamiliar with cloud foundry would look first. Doesn't hurt to have more back and forth links in multiple repos' READMEs to improve discoverability across the board (/cc @ematpl). @onsi might be able to say if there was additional motivation behind the diego repo.

There are things related to diego that don't belong in diego-release per se, e.g. things about lattice, or things about deployment strategies that might start to live elsewhere because diego-release is pretty much never the only release in any deployment manifest containing diego-release jobs (currently consul-agent and metron-agent come form cf-release, and ideal we would explode things even further).

What might make the most sense is to have the top level diego repo have links to all the relevant source and documentation (including the Receptor API docs, as you mention in another issue), and any child repos to have back links to the top level diego repo, as well as "side-links" to any immediately relevant documentation, e.g. diego-release should keep its links to diego-design-notes.

christo4ferris commented 9 years ago

I tend to agree with @shalako. It is unclear why we would create a top level diego, when we don't have one for cloud foundry (aside from cf-release, itself). I think that consistency should reign here. Add the links from 'diego' repo to 'diego-release', and deprecate the 'diego' repo (pointing to 'diego-release') and we're done.

emalm commented 9 years ago

Thanks for your comments, @shalako, @amitkgupta, and @christo4ferris. As to the purpose of the diego repo, @onsi requested in the April Diego update that diego-related issues be opened there, but that seems to have been ignored entirely. Since diego-release is currently the de facto hub for Diego information, I've moved the links from the diego repo to the top of the diego-release README.

As Diego stabilizes, you're correct that the README should focus more on deployment instructions for operators. I'll be restructuring these documents shortly to address both the 'stable' and 'edge' use cases @shalako proposed above and the 'bleeding-edge' case required for development on diego-release, and likely to move the detailed instructions for running the various test suites to a linked CONTRIBUTING document. To be most effective, some of those instructions will depend on tagged final versions of diego-release as proposed in #55, which I expect the team to resolve soon.

Thanks, Eric

emalm commented 9 years ago

We've recently made changes to the diego-release README and CONTRIBUTING documents that address these deployment cases. Closing.