That's a good question. I'm fully for committing docs' changes straight to the "ignite-2.9" branch without introducing superfluous branches such as "ignite-2.9-docs".
Igniters, any notable reason why we can't commit changes to a branch of a finished release? This "frozen" state sounds artificial, might be we can relax it for the docs. @Alexey Goncharuk <agoncha...@gridgain.com> @Nikolay Izhikov <nizhi...@apache.org> @Andrey Gura <ag...@gridgain.com> @Dmitriy Pavlov <dpav...@apache.org> - Denis On Fri, Oct 30, 2020 at 1:12 PM Maxim Muzafarov <mmu...@apache.org> wrote: > Denis, > > Thanks for the answer. Makes sense. > > We already have 2.9.0 tag pointing to the release commit. Is it safe > changing docs right from ignite-2.9 branch? Why should we keep it > frozen? > > On Fri, 30 Oct 2020 at 23:02, Denis Magda <dma...@apache.org> wrote: > > > > Maxim, > > > > The approach you're suggesting (to keep the docs in a separate repo) was > > among the two possible options we were reviewing while deciding where to > > keep the docs. Eventually, we selected the current solution by storing > the > > docs together with the source code in a single repo. > > As a technical writer, I prefer to have a separate repo but the > single-repo > > approach makes more sense when developers contribute to the docs as well. > > > > Anyway, I wouldn't dump the current approach right away. Let's live with > it > > for some time and see if and how we can optimize and amalgamate docs + > dev > > contribution processes. > > > > With ignite-2.9.1, ignite-2.9.2, etc., I would just reuse the same > branch - > > ignite-2.9.0-docs. We can name such branches as ignite-2.9-docs to > > highlight that that single branch is used for any maintenance version of > > the ignite-2.9 release. Thoughts? > > > > - > > Denis > > > > > > On Fri, Oct 30, 2020 at 12:16 PM Maxim Muzafarov <mmu...@apache.org> > wrote: > > > > > Denis, Alex > > > > > > It's a bit confusing for me of having the main dedicated branches for > > > documentation (ignite-2.9-docs, ignite-2.9.1-docs etc.) instead of > > > keeping docs in the release branch. The drawback of freezing all the > > > documentation in the release branch is not good for our users also. > > > > > > We already have the ignite-extensions will it be better to create a > > > dedicated repository (like ignite-docs) for the Ignite docs only? I > > > see the following advantages of this approach: > > > - release and documentation branches have the same name; > > > - the ignite-docs master branch always corresponds to the latest Ignite > > > changes > > > - scope is not frozen by a happened release > > > > > > WDYT? > > > > > > On Fri, 30 Oct 2020 at 20:26, Alex Plehanov <plehanov.a...@gmail.com> > > > wrote: > > > > > > > > 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 > > > > >>> > > > > > > > > > > > >>> > > > > > > > > > > >>> > > > > > > > > > >>> > > > > > > > > >>> > > > > > > > >>> > > > > > > >>> > > > > >> > > > >
