Edgar, Thank you for your point.
I think we are discussing *doc-only projects*, and the docs produced by those projects. So in your example, “State of NFV and OPNFV update” is not applicable here. Those documents are handled by different teams in different ways, and out of scope of our discussion here. If we focus on our scope of discussion, i.e. *doc-only projects*, because those projects were officially approved by TSC, I don’t know what are the reasons why they cannot be included in a release. The point is that we are an inclusive community, and there may be technical reasons that some projects may not be able to pass some criteria and thus be included in a release. However, in general, if a project is approved, it should be included. While from documentation perspective, it may be confusing to some readers, it may be quite straightforward to some other readers depending on how you view it. The same holds true even for projects that produce code: some may think the code is well written for optimization, some may think the code is confusing because of modularity issue. So it depends on how you view it. If there is issue in managing the process, let’s fix it and improve it. So I suggest that we focus on improving the process to better manage those doc-only projects so that they produce higher quality document – just like higher quality code. Thanks Bin From: stpierre, edgar [mailto:edgar.stpie...@dell.com] Sent: Wednesday, September 07, 2016 12:46 PM To: HU, BIN <bh5...@att.com>; David McBride <dmcbr...@linuxfoundation.org>; SULLIVAN, BRYAN L <bs3...@att.com> Cc: opnfv-tech-discuss@lists.opnfv.org Subject: RE: [opnfv-tech-discuss] How are Documentation/Reference Projects Published in C release Hi Bin, To your point, and to Georg’s point earlier: yes, it’s possible to create these artificial linkages for milestones. And I am sure there are documents that will be of value to be aligned with a release. However, I don’t think all documents are tied to a release, and, yes, I think a document repository, if maintained (let’s weed out what’s old and irrelevant as we go along), can be of great value here. As OPNFV delivers on different collateral, it would be of value to have other related collateral also available for download. Case in point: the “State of NFV and OPNFV update” is directly downloaded as PDF from the home page. If this were in a document repository (eventually organized to have marketing, analyst, engineering, and upstream sections for example), then it would provide a whole wealth of related information to the user that just stumbled upon that report. Publically accessible wiki pages are usually works in progress, whereas document repositories capture finished pieces of work. As I look at the current Brahmaputra release documentation page, I find it somewhat confusing for it to be a mix of user guides for current content, technical overviews of current content, and requirements for future content. All intermixed. So, for process: yes, we could continue to make it work. I’m just uncomfortable with whether the end result is best. -edgar From: opnfv-tech-discuss-boun...@lists.opnfv.org<mailto:opnfv-tech-discuss-boun...@lists.opnfv.org> [mailto:opnfv-tech-discuss-boun...@lists.opnfv.org] On Behalf Of HU, BIN Sent: Wednesday, September 07, 2016 3:13 PM To: David McBride; SULLIVAN, BRYAN L Cc: opnfv-tech-discuss@lists.opnfv.org<mailto:opnfv-tech-discuss@lists.opnfv.org> Subject: Re: [opnfv-tech-discuss] How are Documentation/Reference Projects Published in C release David, Please refer to http://lists.opnfv.org/pipermail/opnfv-tech-discuss/2016-September/012465.html for an example of possible milestones, i.e. a subset of current milestones that are applicable to doc-only projects. Thanks Bin From: David McBride [mailto:dmcbr...@linuxfoundation.org] Sent: Wednesday, September 07, 2016 10:52 AM To: SULLIVAN, BRYAN L <bs3...@att.com<mailto:bs3...@att.com>> Cc: HU, BIN <bh5...@att.com<mailto:bh5...@att.com>>; Georg Kunz <georg.k...@ericsson.com<mailto:georg.k...@ericsson.com>>; Adi Molkho <adi.mol...@huawei.com<mailto:adi.mol...@huawei.com>>; Sofia Wallin <sofia.wal...@ericsson.com<mailto:sofia.wal...@ericsson.com>>; Kunzmann, Gerald <kunzm...@docomolab-euro.com<mailto:kunzm...@docomolab-euro.com>>; Daniel Smith <daniel.sm...@ericsson.com<mailto:daniel.sm...@ericsson.com>>; Christopher Price <christopher.pr...@ericsson.com<mailto:christopher.pr...@ericsson.com>>; opnfv-tech-discuss@lists.opnfv.org<mailto:opnfv-tech-discuss@lists.opnfv.org> Subject: Re: [opnfv-tech-discuss] How are Documentation/Reference Projects Published in C release Thanks, Bryan. When I said "quality metrics", I was just using Bin's language. I'm still skeptical about the need for documentation-only projects to participate in a release. To be clear, it isn't a matter of whether I think these projects are important. I also think that there are other ways for projects to publish their requirements document without tying it to a release. However, it's obvious that many in the community think that this is an important thing to do. Therefore, if we're going to continue to associate documentation-only projects with a release, then we need to come up with some milestones and effective gates that provide some transparency beyond those involved in the project, itself. David On Tue, Sep 6, 2016 at 3:46 PM, SULLIVAN, BRYAN L <bs3...@att.com<mailto:bs3...@att.com>> wrote: David, To a point I put into my comments, there is no such thing as a “requirements project” in OPNFV anymore. There are projects, and they have artifacts. If the artifacts are simply documents, there are quality gates that govern them (the gerrit commit review process), and project schedule gates as well. I’m not sure what you mean as “quality metrics” for code contributed in a release, other than gerrit reviews, tests, and project milestones. So I would suggest not to push the analogy too far with documents, as the basis for holding code up as an example is questionable other than the very same things that apply for documents: reviews, tests (to the extent that we test documents as suggested on the opnfvdocs project wiki) and milestones. Thanks, Bryan Sullivan | AT&T From: David McBride [mailto:dmcbr...@linuxfoundation.org<mailto:dmcbr...@linuxfoundation.org>] Sent: Tuesday, September 06, 2016 1:00 PM To: HU, BIN Cc: SULLIVAN, BRYAN L; Georg Kunz; Adi Molkho; Sofia Wallin; Kunzmann, Gerald; Daniel Smith; Christopher Price; opnfv-tech-discuss@lists.opnfv.org<mailto:opnfv-tech-discuss@lists.opnfv.org> Subject: Re: [opnfv-tech-discuss] How are Documentation/Reference Projects Published in C release Bin, You hit on a key point: "meets milestones and other quality metrics". One reason that I question whether requirements projects should join a release is that the requirements projects associated with Colorado responded with "N/A" for most or all of their milestone reporting. That's understandable, since the milestones are oriented toward projects that are creating or modifying code. I'm not aware of any quality metrics that they have been subjected to. So, that raises the question, should requirements projects be tracked in a release? If so, what milestones or other metrics should be used to track them? David On Tue, Sep 6, 2016 at 12:07 PM, HU, BIN <bh5...@att.com<mailto:bh5...@att.com>> wrote: +1 for Bryan’s point. If a project requests its docs to be included in release documentation, and it meets milestones and other quality metrics and won’t pose any adversary effects on release schedule, it should be included. Many documentation provides “knowledge”, as Heather indicated in a separate thread, and is very valuable to industry. Thanks Bin From: opnfv-tech-discuss-boun...@lists.opnfv.org<mailto:opnfv-tech-discuss-boun...@lists.opnfv.org> [mailto:opnfv-tech-discuss-boun...@lists.opnfv.org<mailto:opnfv-tech-discuss-boun...@lists.opnfv.org>] On Behalf Of SULLIVAN, BRYAN L Sent: Tuesday, September 06, 2016 9:40 AM To: Georg Kunz <georg.k...@ericsson.com<mailto:georg.k...@ericsson.com>>; Adi Molkho <adi.mol...@huawei.com<mailto:adi.mol...@huawei.com>>; Sofia Wallin <sofia.wal...@ericsson.com<mailto:sofia.wal...@ericsson.com>>; Kunzmann, Gerald <kunzm...@docomolab-euro.com<mailto:kunzm...@docomolab-euro.com>>; Daniel Smith <daniel.sm...@ericsson.com<mailto:daniel.sm...@ericsson.com>>; David McBride <dmcbr...@linuxfoundation.org<mailto:dmcbr...@linuxfoundation.org>>; Christopher Price <christopher.pr...@ericsson.com<mailto:christopher.pr...@ericsson.com>> Cc: opnfv-tech-discuss@lists.opnfv.org<mailto:opnfv-tech-discuss@lists.opnfv.org> Subject: Re: [opnfv-tech-discuss] How are Documentation/Reference Projects Published in C release ***Security Advisory: This Message Originated Outside of AT&T *** Reference http://cso.att.com/EmailSecurity/IDSP.html for more information. My take is that we have projects, and those projects create documents that are optionally (on request of the project) included in the release documentation. We need go no further than that. Labelling projects (something I thought we had moved away from) or types of documents/focuses (e.g. requirements) and applying different policies as to what/how they are included in the release documentation, is unnecessary and ultimately confusing to the community. As an example, my Copper project documentation<http://artifacts.opnfv.org/copper/docs/design/index.html> is one document (a “design” document but that’s only a repo folder naming convention) that addresses the subject completely – e.g. use cases, architecture, requirements, and implementation approaches. I see no reason to apply a different policy to the separate sections of this document based upon their focus, and I don’t intend to. The document itself addresses what is specific to Colorado, can what is possible future work. This will be what is published for Copper. Thanks, Bryan Sullivan | AT&T From: opnfv-tech-discuss-boun...@lists.opnfv.org<mailto:opnfv-tech-discuss-boun...@lists.opnfv.org> [mailto:opnfv-tech-discuss-boun...@lists.opnfv.org] On Behalf Of Georg Kunz Sent: Tuesday, September 06, 2016 8:56 AM To: Adi Molkho; Sofia Wallin; Kunzmann, Gerald; Daniel Smith; David McBride; Christopher Price Cc: opnfv-tech-discuss@lists.opnfv.org<mailto:opnfv-tech-discuss@lists.opnfv.org> Subject: Re: [opnfv-tech-discuss] How are Documentation/Reference Projects Published in C release Hi Adi, We had a discussion on this in the docs meeting last week and to my understanding we came to the agreement that the requirement docs should be included. The exact location and the naming still needs to be decided upon. For instance, it should be clear for users of the release that the requirement docs do NOT describe features which are available in the release. One proposal is to add a section to the documentation library called “Requirement Analyses” (my favorite) or “Future Work” (indicating that the requirements identified by the requirement docs will hopefully be addressed in future releases. I hope we can conclude on the details soon, either here on the list or in tomorrow’s docs meeting. Georg From: Adi Molkho [mailto:adi.mol...@huawei.com] Sent: Tuesday, September 06, 2016 3:40 PM To: Sofia Wallin; Kunzmann, Gerald; Georg Kunz; Daniel Smith; David McBride; Christopher Price Cc: opnfv-tech-discuss@lists.opnfv.org<mailto:opnfv-tech-discuss@lists.opnfv.org> Subject: RE: [opnfv-tech-discuss] How are Documentation/Reference Projects Published in C release Hi Is there any final conclusion to this mail thread ? Are the documents of the requirement project going to be part of the C release? Thanks Adi From: opnfv-tech-discuss-boun...@lists.opnfv.org<mailto:opnfv-tech-discuss-boun...@lists.opnfv.org> [mailto:opnfv-tech-discuss-boun...@lists.opnfv.org]<mailto:[mailto:opnfv-tech-discuss-boun...@lists.opnfv.org]> On Behalf Of Sofia Wallin Sent: Wednesday, August 31, 2016 1:42 PM To: Kunzmann, Gerald; Georg Kunz; Daniel Smith; David McBride; Christopher Price Cc: opnfv-tech-discuss@lists.opnfv.org<mailto:opnfv-tech-discuss@lists.opnfv.org> Subject: Re: [opnfv-tech-discuss] How are Documentation/Reference Projects Published in C release Hi everyone, I haven’t been involved in the discussion whether we want the requirement projects to be a part of our releases or not. But when it comes to documentation it is obvious that people see a need to include this kind of work as well. I agree with Chris, “to publish a “future work” section of our release library that describes more where our community is heading”. I talked to Daniel yesterday and we think that it would be fine to handle this in the same way as the release documentation. We create an introduction document explaining what this is about and link to the projects documentation. But let’s discuss this (and hopefully agree), I will add this as topic for the docs meeting this afternoon, so people concerned are welcome to call in. BR, Sofia From: opnfv-tech-discuss-boun...@lists.opnfv.org<mailto:opnfv-tech-discuss-boun...@lists.opnfv.org> [mailto:opnfv-tech-discuss-boun...@lists.opnfv.org] On Behalf Of Kunzmann, Gerald Sent: den 31 augusti 2016 09:51 To: Georg Kunz; Daniel Smith; David McBride Cc: opnfv-tech-discuss@lists.opnfv.org<mailto:opnfv-tech-discuss@lists.opnfv.org> Subject: Re: [opnfv-tech-discuss] How are Documentation/Reference Projects Published in C release Hi David, all, My 2 cent on your question: The question is: does it make sense for requirements projects to participate in releases until they're ready to deliver code? Requirement projects are an essential part of OPNFV and some may even do all development in upstream, i.e. there might even be no code within OPNFV except test cases. Thus, I support having the requirement documents as part of the release documentation. Best regards, Gerald From: opnfv-tech-discuss-boun...@lists.opnfv.org<mailto:opnfv-tech-discuss-boun...@lists.opnfv.org> [mailto:opnfv-tech-discuss-boun...@lists.opnfv.org] On Behalf Of Georg Kunz Sent: Mittwoch, 31. August 2016 09:42 To: Daniel Smith <daniel.sm...@ericsson.com<mailto:daniel.sm...@ericsson.com>>; David McBride <dmcbr...@linuxfoundation.org<mailto:dmcbr...@linuxfoundation.org>> Cc: opnfv-tech-discuss@lists.opnfv.org<mailto:opnfv-tech-discuss@lists.opnfv.org> Subject: Re: [opnfv-tech-discuss] How are Documentation/Reference Projects Published in C release Hi Daniel, hi all, Thank you Daniel for stating the advantages for the requirements projects and for OPNFV. From my point of view it is important for projects which are currently in the “requirements phase” to be represented in an OPNFV release: - We are in the process of reaching out to the OpenStack community based on our document. Making the requirements document an official part of an OPNFV release helps us in doing that by having an “official backing” of OPNFV (we are an OPNFV project after all) - It shows to the outside world that projects are active in all phases (requirements phase), supporting the overall perception of OPNFV - It gives the project members the feeling of contributing to OPNFV I had some discussions with Chris and Sofia on this during the OPNFV summit. Back then the proposal was to include our requirements document in the “document library” under a section such as “requirements projects”. This could be a simple link – just as we have it right now on our project wiki. As David pointed out, there is some overhead involved for the project, but I believe the benefits outweigh the overhead. Looking forward to discussing with you in today’s docs meeting. Best regards Georg From: opnfv-tech-discuss-boun...@lists.opnfv.org<mailto:opnfv-tech-discuss-boun...@lists.opnfv.org> [mailto:opnfv-tech-discuss-boun...@lists.opnfv.org] On Behalf Of Daniel Smith Sent: Tuesday, August 30, 2016 11:44 PM To: David McBride Cc: opnfv-tech-discuss@lists.opnfv.org<mailto:opnfv-tech-discuss@lists.opnfv.org> Subject: Re: [opnfv-tech-discuss] How are Documentation/Reference Projects Published in C release Hey All. I spoke with Sofia as well about this and presented our NetReady situation. We have a document that covers what we wanted to cover for Phase 1 (targeting C release) of the NetReady Requirements Project. We now want to stop internally editing it and release it for comment – and the thinking is that, since we have built the document in gerrit and based on DOCS formatting guidelines, was the vehicle to provide the following in terms of the work that the team did: - Allow for the completion and publishing of the Project Goals Phase 1 targets (in line with agreed principles when the project was approved/started) – Phase2,3,4 as outlined are targeted for subsequent releases as documented - Allow for the distribution of the finished product to external (non commiter/contributer groups) - is it realistic to think that someone from Openstack (whom the requirements are destined for) will look at the RST line format in our gerrit repository to find our documentation? (rather than in the released docs page/artifact)? Or perhaps a different way of looking at it would be to ask, how do we move the finished requirements document for C release to a platform to be viewed and commented (i.e JIRA for D release for review or in gerrit) going forward - Allows us to tag and timestamp the work (and thus the evolution) of the work the team is doing. Provides start and stop points to coordinate work for the team (goal/endpoints). - Allows all projects to feel that they are contributing to a finished release product o Further to that maybe this plays into the idea of “release participation” discussion. At any rate, I thought that Sofia’s response of there would be a ../release/Colorado/docs/RequirementProcject page in the final release that would point to the links that requirements projects delivered and that made sense to me. In the end do as you see fit of course, I would wonder about how requirements projects are to gain inclusiveness in releases and how that affects the ability to trace back to “why did we make this code” when that comes time – since that backstory would have to be ported at that point. Thank you all for the responses. Daniel From: David McBride [mailto:dmcbr...@linuxfoundation.org]<mailto:[mailto:dmcbr...@linuxfoundation.org]> Sent: Tuesday, August 30, 2016 2:25 PM To: Daniel Smith <daniel.sm...@ericsson.com<mailto:daniel.sm...@ericsson.com>> Cc: Sofia Wallin <sofia.wal...@ericsson.com<mailto:sofia.wal...@ericsson.com>>; opnfv-tech-discuss@lists.opnfv.org<mailto:opnfv-tech-discuss@lists.opnfv.org> Subject: Re: [opnfv-tech-discuss] How are Documentation/Reference Projects Published in C release Hi Daniel, We've had some discussion about this in various meetings, including hackfest, over the past several weeks. The question is: does it make sense for requirements projects to participate in releases until they're ready to deliver code? It's not clear to me that there's any advantage to either the project, or OPNFV as a whole. Furthermore, there's a certain amount of overhead for each project that participates in the release, so if there's no advantage, then perhaps it would be better to wait to join the release until the project is prepared to deliver code. However, I'm open to alternative viewpoints. Thanks. David On Tue, Aug 30, 2016 at 12:29 PM, Daniel Smith <daniel.sm...@ericsson.com<mailto:daniel.sm...@ericsson.com>> wrote: Hey David and Sofia. In the NetReady group, we have structured our documentation and commits for our C-release documentation in RST format/doc guidelines under the auspices that this was required so that when the DOCS are generated for the release, requirements and documentation projects deliveries are included in the release. In our meeting there was some confusion as to how Requirements Projects, that delivery requirements documents (which are finalized for this phase and then later phases – prototyping, etc occurs for D release, based on the C deliveable) are actually included in the release. Some input was that Requirements projects, since they don’t deliver code are not part of the release? That didn’t sound correct me, so please clarify when you have time. Thank you [Ericsson]<http://www.ericsson.com/> Daniel Smith Sr. System Designer Ericsson Inc. 8400 Decarie Blvd. Montreal, PQ (514)-594-2799<tel:%28514%29-594-2799> [http://www.ericsson.com/current_campaign]<http://www.ericsson.com/current_campaign> Legal entity: Ericsson AB, registered office in Stockholm. This Communication is Confidential. We only send and receive email on the basis of the terms set out at www.ericsson.com/email_disclaimer<http://www.ericsson.com/email_disclaimer> -- David McBride Release Manager, OPNFV Mobile: +1.805.276.8018<tel:%2B1.805.276.8018> Email/Google Talk: dmcbr...@linuxfoundation.org<mailto:dmcbr...@linuxfoundation.org> Skype: davidjmcbride1 IRC: dmcbride -- David McBride Release Manager, OPNFV Mobile: +1.805.276.8018<tel:%2B1.805.276.8018> Email/Google Talk: dmcbr...@linuxfoundation.org<mailto:dmcbr...@linuxfoundation.org> Skype: davidjmcbride1 IRC: dmcbride -- David McBride Release Manager, OPNFV Mobile: +1.805.276.8018<tel:%2B1.805.276.8018> Email/Google Talk: dmcbr...@linuxfoundation.org<mailto:dmcbr...@linuxfoundation.org> Skype: davidjmcbride1 IRC: dmcbride
_______________________________________________ opnfv-tech-discuss mailing list opnfv-tech-discuss@lists.opnfv.org https://lists.opnfv.org/mailman/listinfo/opnfv-tech-discuss
