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 > > > > > > > > > > > > > > > > > > > > >
