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