Where to store the released spec doc?

[Emily Jiang]

As part of Config release preparation, we need a place to store the released spec doc. As normally repo only hosts the archive files. The .pdf will not be uploaded to Eclipse repo or maven repo. I have not found any doc hosted in the maven repo either. In my view, the doc should be stored somewhere in MicroProfile repo, similar to JSR specs. With that, I propose to create a dedicated repo, e.g. microprofile-released-specs, to store all released specs (e.g. Config). Thoughts?

Emily

[Kevin Sutter]

Emily, I brought this up to Ken in the review of the revamped evolution process -- thinking that the old evolution-process repo could still be used to store the proposals and spec.  What about this idea...  Why not just check in the final pdf into your microprofile-config repo and then we could have a Wiki page dedicated to pointing at the completed specs?  Pretty easy without much overhead.  Would that work?  Your idea of setting up an alternate repo would also work, just wondering whether it's necessary or not.

--  Kevin

[Emily Jiang]

Good thoughts, Kevin. The only issue is that repo name evolution-process is not self explanatory. We could rename the repo name to be microprofile-released-specs. I would rather create a new one for a cleaner history. The advantages of having a dedicated repo is to put all specs together. Yes, we can upload the spec pdf on config 1.0 branch when it is released. I gather all options here from Kevin and me to see what other people think.

1. create microprofile-released-specs to store all specs

2. reuse evolution-process and check in the specs: I am not sure about the repo name:o.

3. check in the .pdf to the released repo e.g. config 1.0 and create a wiki entry to point to it.

Emily

[Kevin Sutter]

Regardless of where we store them, we still need a wiki page for ease of access.

--  Kevin

[Ken Finnigan]

+1 to the spec pdf being committed into the repository in which it relates, and then a Wiki page linking to the spec pdf for each spec.

I fear that yet another repository to store the specs is just another step across repositories that complicates the release process

Ken

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.
To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/dddc87df-a9b5-43b0-9350-3d3b0399eb9b%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Kevin Sutter]

Ken,
On our bi-weekly hangout, this question also came up in relation to our finalized Proposals.  In the past, our finalized Proposals were just kept as part of the evolution-process repo.  But, now that we are deep-sixing that repo, should we also contain the finalized Proposal in our respective component repos?  And, provide a link in our wiki?  I think that sounds good.

John also mentioned that he was going to experiment with a spreadsheet or wiki page or something to consolidate all of this material on the various specs -- proposals, specs, repo links, proposed dates, proposed mp content, etc.  Having some centralized location to go find this information would be excellent.

Thanks, Kevin

[John D. Ament]

Assuming we have a tag of the repo, I think the most we should do is keep a copy of the PDF out on the wiki.  No reason to commit it to a git repo.   I always  hate the idea of committing build artifacts.

John

[Ken Finnigan]

Sorry for delayed response, was on holiday (moving).

I think I threw out the idea of adding the PDF to the respective repos, but agree with John that adding build artifacts to git would be bad.

I think it makes sense for part of the release process to for each specification to include generating the PDF specification and adding it to the wiki, or some other coordinated location. Maybe the wiki needs a section for each proposal that is essentially a landing page for that specification? That page could then hold a releases table of that specification with attached PDFs of spec for each release?

Ideally the entirety of MP would then have something similar that linked out to the specifications and their versions that were part of each release. Maybe the specification page also needs a link back to MP release page for each version of spec that's part of a MP release. Cross linking FTW!

Ken

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/236ec226-520f-441a-9957-e783a3d27a60%40googlegroups.com.

[Emily Jiang]

I am wondering how to do the version control if we store the released specs on our wiki. I think storing the pdf on the corresponding repo will guarantee the version.

Emily

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/dddc87df-a9b5-43b0-9350-3d3b0399eb9b%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.

[Ken Finnigan]

Not sure what version control would be required, can you elaborate?

My thought was simply that each release is a snapshot in time of the spec, so they would be uploaded separately as opposed to having a single entry with a history.

Then there would be a release table of some kind that has a row for each version, with separate links to open each versions specification.

As not all implementations will be on the same version at the same time, it's essential that we make available each specification version separately.

Ken

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/349f501d-7d76-4cca-b09b-06e3115cc21f%40googlegroups.com.

[Heiko Rupp]

GitHub also has this release mechanism, where full archive snapshots can be uploaded. I think that would also allow to put the respective PDF out there.

We can then in the Wiki point to that GH URL.

Ken

[Emily Jiang]

Yes, Heiko. That is exactly I think we were trying to do.

Ken, if we upload the release pdf to wiki. Everyone of us can freely update it or delete it by mistake. It is difficult to verify its originality. I still think what we tried to do originally is good. In my view, uploading the pdf file to the release is the best option so far.

Emily

[Ondrej Mihályi]

While PDFs can be put to the wiki and even versioned if we want, working with the Eclipse Wiki is really awkward as I found out.

I realized that GitHub automatically picked up the tag created by the maven release plugin and created a release. I modified the release and uploaded the PDF, here's how it looks: https://github.com/eclipse/microprofile-config/releases/tag/1.0-RC1

I think that using github releases feature is a more user-friendly way of publishing PDFs than using the Wiki. But I think that storing PDFs in a maven repo would be even more user-friendly, as it's automatically versioned, can be easily fully automated and can be linked directly using an URL. I even think that we could deploy PDF files directly, not packaged as ZIP, using a custom maven packaging as described here. I'll try to do it when I have time.

We also need a place to aggregate all the information about an MP feature and it's releases, ideally automatically updated from the release scripts to avoid too many manual steps. This could be done by generating some metadata that could be picked up by the microprofile.io page, or generating a snippet of wiki markup that could be copy&pasted into the Eclipse wiki.

I'm a big fan of automation, therefore I really prefer a solution that can be automated as much as possible. Manual steps are tedious and error-prone.

--Ondro

[Ken Finnigan]

If the wiki is not the appropriate place to store generated PDFs, then I think making it an artifact that's deployed to central is the best option.

Then it's an artifact of the build, as opposed to needing a subsequent commit to add the PDF into the repository. The latter approach also adds risk that it's not updated when it should be.

Ken

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/fe150a3a-c6d6-419e-92b9-3fa30175cdf6%40googlegroups.com.