Igniters, I've created "ignite-2.9-docs" branch and cherry-picked documentation related commits from master. If you changing documentation in master branch and this fix should affect Ignite 2.9, please cherry-pick this commit to "ignite-2.9-docs" branch too.
чт, 15 окт. 2020 г. в 01:58, Denis Magda <dma...@apache.org>: > Igniters, > > I've put together the first version of the documentation contribution and > publication process that is based on the new documentation engine we're > releasing with Ignite 2.9: > https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document > > Please find some time to check it out and suggest any changes. Let's > discuss this. At least, I'd like to hear your opinion on the following > items: > > - A relaxed procedure is applied to minor changes (typos, > unclarities), with no need to create a JIRA ticket and go through the > pull-request procedure: > > https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document#HowtoDocument-ContributingMinorChanges > - We're freezing a branch of a release once it's finished. This makes > it impossible to use the release branch for documentation changes that will > follow after. I'm suggesting to create another branch for the docs needs > once the release is finished. @Alex Plehanov <plehanov.a...@gmail.com> can > we try out this approach for Ignite 2.9?: > > https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document#HowtoDocument-UpdatingReleasedDocs > > > - > Denis > > > On Fri, Mar 20, 2020 at 9:24 AM Denis Magda <dma...@apache.org> wrote: > >> Hi Maxim, >> >> Those JIRA labels support the current process that assumes the creation >> of a documentation ticket before a development ticket is closed. If a >> contributor believes there is no need to update the docs (like in the case >> of bug fixes) then "Documentation required" will stay disabled. Otherwise, >> we need to work on the docs and "Documentation required" needs to be on, >> and a docs ticket has to be created. That's the current process... that >> should be revisited and changed. I've recorded that item of us in this >> discussion: >> http://apache-ignite-developers.2346864.n4.nabble.com/DISCUSSION-Major-changes-in-Ignite-in-2020-td46579.html >> >> Generally, I like the idea shared by Andrey Gura that documentation and >> APIs need to be updated and prepared before a primary development ticket is >> closed. As a side effect, we'll get rid off "Documentation required" label. >> >> - >> Denis >> >> >> On Fri, Mar 20, 2020 at 7:03 AM Maxim Muzafarov <mmu...@apache.org> >> wrote: >> >>> Denis, >>> >>> From my recent practice with the release check-boxes "Release notes >>> required" and "Documentation required" also was not so helpful as >>> expected. Can we remove them from JIRA issues? >>> >>> There is no magic pill to not forget to document improvements, but I >>> think a wide discussion of each major improvement on the dev-list can >>> help much to keep documentation up to date. >>> >>> On Thu, 19 Mar 2020 at 23:18, Alexey Zinoviev <zaleslaw....@gmail.com> >>> wrote: >>> > >>> > The Best way to require draft documentation with the proposed PR:) as a >>> > part of TC check >>> > >>> > чт, 19 мар. 2020 г., 21:06 Denis Magda <dma...@apache.org>: >>> > >>> > > Igniters, >>> > > >>> > > I've modified our release process introducing this step that ensures >>> > > documentation readiness before a vote can be started: >>> > > >>> > > >>> https://cwiki.apache.org/confluence/display/IGNITE/Release+Process#ReleaseProcess-4.1EnsureDocumentationReadinessandAccouncementBlogPostActivity >>> > > >>> > > Thanks to everyone who joined this conversation. >>> > > >>> > > - >>> > > Denis >>> > > >>> > > >>> > > On Wed, Mar 18, 2020 at 2:17 AM Artem Budnikov < >>> > > a.budnikov.ign...@gmail.com> >>> > > wrote: >>> > > >>> > > > Denis, >>> > > > >>> > > > Both yours and Andrey's proposal are important. You should start >>> to vote >>> > > > after the documentation is ready, just like you start to vote >>> after all >>> > > > features are ready, and documentation is just another feature. >>> However, >>> > > the >>> > > > documentation can't be prepared if there is no information on the >>> > > features. >>> > > > Implementing the feature and working on the docs should go in >>> tandem. As >>> > > > Andrey pointed out it brings some benefits, and makes you more >>> > > > conscious about the "user" aspect of the feature, which is >>> generally a >>> > > good >>> > > > thing. >>> > > > >>> > > > -Artem >>> > > > >>> > > > On Tue, Mar 17, 2020 at 11:59 PM Denis Magda <dma...@apache.org> >>> wrote: >>> > > > >>> > > > > Hi Pavel, >>> > > > > >>> > > > > We're thinking about the same in regards to the future of Ignite >>> > > > > documentation :) Artem and I had some kitchen talks recently and >>> we'll >>> > > > > restart that activity. Ignite definitely deserves and requires >>> next-gen >>> > > > > docs. Artem promised to share his thoughts soon. >>> > > > > >>> > > > > Btw, check out How to write effective documentation for your >>> > > open-source >>> > > > > projec <https://opensource.com/article/20/3/documentation>t >>> article >>> > > > that I >>> > > > > found in one of my newsletters today. It feels like it can be >>> used as a >>> > > > > reference by Igniters on some best practices. >>> > > > > >>> > > > > Denis Magda >>> > > > > >>> > > > > >>> > > > > On Tue, Mar 17, 2020 at 1:03 PM Pavel Tupitsyn < >>> ptupit...@apache.org> >>> > > > > wrote: >>> > > > > >>> > > > > > I agree with Andrey. >>> > > > > > >>> > > > > > And I'd like to reopen the discussion on "moving docs from >>> readme.io >>> > > > to >>> > > > > > git" [1] [2] >>> > > > > > Looks like we reached some agreement there but never moved on >>> with >>> > > the >>> > > > > > migration. >>> > > > > > >>> > > > > > >>> > > > > > [1] >>> > > > > > >>> > > > > > >>> > > > > >>> > > > >>> > > >>> http://apache-ignite-developers.2346864.n4.nabble.com/Move-documentation-from-readme-io-to-GitHub-pages-td16409.html >>> > > > > > [2] https://issues.apache.org/jira/browse/IGNITE-7595 >>> > > > > > >>> > > > > > On Tue, Mar 17, 2020 at 9:48 PM Denis Magda <dma...@apache.org >>> > >>> > > wrote: >>> > > > > > >>> > > > > > > Andrey, >>> > > > > > > >>> > > > > > > Thanks for sharing your thoughts. Your second point made me >>> recall >>> > > > > > several >>> > > > > > > occasions when only after a release of some public APIs we >>> had a >>> > > > chance >>> > > > > > to >>> > > > > > > complete documentation and discovered the APIs' >>> ineffectiveness and >>> > > > > > oddness >>> > > > > > > from the user usage perspective. But it was already late. >>> > > > > > > >>> > > > > > > Generally, if to move incrementally with documentation >>> process >>> > > > changes, >>> > > > > > > "documentation readiness before the vote" should work as the >>> first >>> > > > step >>> > > > > > for >>> > > > > > > us. There will be delays with the vote for sure because we >>> have to >>> > > > get >>> > > > > > used >>> > > > > > > to this change, but over time we should get to the point when >>> > > > > > documentation >>> > > > > > > will be prepared upon overall task resolution. Andrey, >>> Artem, do >>> > > you >>> > > > > > agree >>> > > > > > > with that? >>> > > > > > > >>> > > > > > > Other community members, please share your thoughts. If we >>> don't >>> > > hear >>> > > > > any >>> > > > > > > opposite opinions, then I would update our release >>> procedures with >>> > > > this >>> > > > > > > change. >>> > > > > > > >>> > > > > > > - >>> > > > > > > Denis >>> > > > > > > >>> > > > > > > >>> > > > > > > On Mon, Mar 16, 2020 at 9:44 AM Andrey Gura < >>> ag...@apache.org> >>> > > > wrote: >>> > > > > > > >>> > > > > > > > Denis, >>> > > > > > > > >>> > > > > > > > I agree with you. >>> > > > > > > > >>> > > > > > > > Also I think that we should move to process which will >>> require >>> > > > > > > > documentation updates during work on issue/feature and >>> will part >>> > > of >>> > > > > > > > code review process. Such approach has some useful >>> benefits: >>> > > > > > > > >>> > > > > > > > - Documentation readiness at the same time when >>> > > fix/implementation >>> > > > is >>> > > > > > > > ready (remember, documentation is part of a product). >>> > > > > > > > - Work on documentation and review could discover >>> incompleteness >>> > > > of a >>> > > > > > > > fix or a feature on earlier stage (It is usual situation >>> when >>> > > some >>> > > > > > > > aspects were just forgotten, but documentation writing >>> could >>> > > > > spotlight >>> > > > > > > > such things). >>> > > > > > > > >>> > > > > > > > On Thu, Mar 12, 2020 at 7:49 PM Denis Magda < >>> dma...@apache.org> >>> > > > > wrote: >>> > > > > > > > > >>> > > > > > > > > Igniters, >>> > > > > > > > > >>> > > > > > > > > With the final 2.8 release steps checked out today by >>> > > announcing >>> > > > > the >>> > > > > > > > > version globally (congrats!), it's a proper time to >>> consider >>> > > and >>> > > > > > tweak >>> > > > > > > > our >>> > > > > > > > > release process, making completion of some phases more >>> > > > predictable >>> > > > > > and >>> > > > > > > > > aligned. I would like to dedicate this thread solely to >>> changes >>> > > > > > related >>> > > > > > > > to >>> > > > > > > > > the documentation. >>> > > > > > > > > >>> > > > > > > > > If to do a recap, Ignite 2.8 announcement went out of >>> sync with >>> > > > the >>> > > > > > > > > publication of binaries, Maven and other artifacts >>> because our >>> > > > > > > technical >>> > > > > > > > > documentation was completed long after the vote had been >>> > > closed. >>> > > > > > > > > >>> > > > > > > > > We can easily eliminate such glitches for future >>> releases if >>> > > > agree >>> > > > > to >>> > > > > > > > start >>> > > > > > > > > a vote only if Ignite docs are ready and can be >>> published the >>> > > > same >>> > > > > > day >>> > > > > > > > with >>> > > > > > > > > other release artifacts. If the docs are completed and >>> > > available >>> > > > > > > > > internally while the vote goes then we can work on a >>> release >>> > > blog >>> > > > > > post >>> > > > > > > > > (referring to docs details) and announce the release the >>> same >>> > > day >>> > > > > > when >>> > > > > > > > the >>> > > > > > > > > binaries/docs availability. >>> > > > > > > > > >>> > > > > > > > > Thoughts? Let's change the process ensuring that the >>> vote can >>> > > be >>> > > > > > > started >>> > > > > > > > > only if technical documentation is ready to be released? >>> > > > > > > > > >>> > > > > > > > > - >>> > > > > > > > > Denis >>> > > > > > > > >>> > > > > > > >>> > > > > > >>> > > > > >>> > > > >>> > > >>> >>
