[DISCUSSION] Changes in Ignite release process related to documentation

[dmagda]

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

Hi Denis,

My suggestion is that in the current version release process, when
planning to release a version, first determine the Time, Scope and
ReleaseManager. On this basis, we can add another work of documentation,
which is to determine which documents need to be written and who should
write them,instead of adding documents after all the work is done.

在 2020/3/13 上午12:49, Denis Magda 写道:

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

[agura]

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 <[hidden email]> 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

[dmagda]

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 <[hidden email]> 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 <[hidden email]> 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
>

[Pavel Tupitsyn]

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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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
> >
>

[dmagda]

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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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
> > >
> >
>

[Artem Budnikov]

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 <[hidden email]> 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 <[hidden email]>
> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]>
> 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
> > > >
> > >
> >
>

[dmagda]

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 <[hidden email]>
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 <[hidden email]> 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 <[hidden email]>
> > 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 <[hidden email]> 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 <[hidden email]>
> 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 <[hidden email]>
> > 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
> > > > >
> > > >
> > >
> >
>

[Alexey Zinoviev]

The Best way to require draft documentation with the proposed PR:) as a
part of TC check

чт, 19 мар. 2020 г., 21:06 Denis Magda <[hidden email]>:

> 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 <
> [hidden email]>
> 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 <[hidden email]> 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 <[hidden email]>
> > > 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 <[hidden email]>
> 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 <[hidden email]>
> > 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 <[hidden email]>
> > > 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
> > > > > >
> > > > >
> > > >
> > >
> >
>

[Maxim Muzafarov]

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 <[hidden email]> wrote:

>
> The Best way to require draft documentation with the proposed PR:) as a
> part of TC check
>
> чт, 19 мар. 2020 г., 21:06 Denis Magda <[hidden email]>:
>
> > 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 <
> > [hidden email]>
> > 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 <[hidden email]> 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 <[hidden email]>
> > > > 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 <[hidden email]>
> > 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 <[hidden email]>
> > > 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 <[hidden email]>
> > > > 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
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >

[dmagda]

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 <[hidden email]> 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 <[hidden email]>
> wrote:
> >
> > The Best way to require draft documentation with the proposed PR:) as a
> > part of TC check
> >
> > чт, 19 мар. 2020 г., 21:06 Denis Magda <[hidden email]>:
> >
> > > 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 <
> > > [hidden email]>
> > > 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 <[hidden email]>
> 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 <
> [hidden email]>
> > > > > 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 <[hidden email]>
> > > 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 <[hidden email]>
> > > > 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 <
> [hidden email]>
> > > > > 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
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
>

[dmagda]

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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]>
>> wrote:
>> >
>> > The Best way to require draft documentation with the proposed PR:) as a
>> > part of TC check
>> >
>> > чт, 19 мар. 2020 г., 21:06 Denis Magda <[hidden email]>:
>> >
>> > > 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 <
>> > > [hidden email]>
>> > > 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 <[hidden email]>
>> 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 <
>> [hidden email]>
>> > > > > 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 <[hidden email]>
>> > > 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 <[hidden email]
>> >
>> > > > 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 <
>> [hidden email]>
>> > > > > 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
>> > > > > > > >
>> > > > > > >
>> > > > > >
>> > > > >
>> > > >
>> > >
>>
>

[Alexey Plekhanov]

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 <[hidden email]>:

> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]>
>> 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 <[hidden email]>
>>> wrote:
>>> >
>>> > The Best way to require draft documentation with the proposed PR:) as a
>>> > part of TC check
>>> >
>>> > чт, 19 мар. 2020 г., 21:06 Denis Magda <[hidden email]>:
>>> >
>>> > > 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 <
>>> > > [hidden email]>
>>> > > 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 <[hidden email]>
>>> 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 <
>>> [hidden email]>
>>> > > > > 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 <[hidden email]
>>> >
>>> > > 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 <
>>> [hidden email]>
>>> > > > 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 <
>>> [hidden email]>
>>> > > > > 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
>>> > > > > > > >
>>> > > > > > >
>>> > > > > >
>>> > > > >
>>> > > >
>>> > >
>>>
>>

[Maxim Muzafarov]

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 <[hidden email]> 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 <[hidden email]>:
>
> > 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]>
> >> 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 <[hidden email]>
> >>> wrote:
> >>> >
> >>> > The Best way to require draft documentation with the proposed PR:) as a
> >>> > part of TC check
> >>> >
> >>> > чт, 19 мар. 2020 г., 21:06 Denis Magda <[hidden email]>:
> >>> >
> >>> > > 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 <
> >>> > > [hidden email]>
> >>> > > 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 <[hidden email]>
> >>> 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 <
> >>> [hidden email]>
> >>> > > > > 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 <[hidden email]
> >>> >
> >>> > > 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 <
> >>> [hidden email]>
> >>> > > > 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 <
> >>> [hidden email]>
> >>> > > > > 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
> >>> > > > > > > >
> >>> > > > > > >
> >>> > > > > >
> >>> > > > >
> >>> > > >
> >>> > >
> >>>
> >>

[dmagda]

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 <[hidden email]> 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 <[hidden email]>
> 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 <[hidden email]>:
> >
> > > 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 <
> [hidden email]> 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 <[hidden email]> 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 <[hidden email]>
> > >> 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 <
> [hidden email]>
> > >>> wrote:
> > >>> >
> > >>> > The Best way to require draft documentation with the proposed PR:)
> as a
> > >>> > part of TC check
> > >>> >
> > >>> > чт, 19 мар. 2020 г., 21:06 Denis Magda <[hidden email]>:
> > >>> >
> > >>> > > 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 <
> > >>> > > [hidden email]>
> > >>> > > 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 <
> [hidden email]>
> > >>> 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 <
> > >>> [hidden email]>
> > >>> > > > > 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 <
> [hidden email]
> > >>> >
> > >>> > > 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 <
> > >>> [hidden email]>
> > >>> > > > 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 <
> > >>> [hidden email]>
> > >>> > > > > 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
> > >>> > > > > > > >
> > >>> > > > > > >
> > >>> > > > > >
> > >>> > > > >
> > >>> > > >
> > >>> > >
> > >>>
> > >>
>

[Maxim Muzafarov]

 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]>
> > 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 <[hidden email]>:
> > >
> > > > 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 <
> > [hidden email]> 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 <[hidden email]> 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 <[hidden email]>
> > > >> 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 <
> > [hidden email]>
> > > >>> wrote:
> > > >>> >
> > > >>> > The Best way to require draft documentation with the proposed PR:)
> > as a
> > > >>> > part of TC check
> > > >>> >
> > > >>> > чт, 19 мар. 2020 г., 21:06 Denis Magda <[hidden email]>:
> > > >>> >
> > > >>> > > 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 <
> > > >>> > > [hidden email]>
> > > >>> > > 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 <
> > [hidden email]>
> > > >>> 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 <
> > > >>> [hidden email]>
> > > >>> > > > > 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 <
> > [hidden email]
> > > >>> >
> > > >>> > > 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 <
> > > >>> [hidden email]>
> > > >>> > > > 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 <
> > > >>> [hidden email]>
> > > >>> > > > > 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
> > > >>> > > > > > > >
> > > >>> > > > > > >
> > > >>> > > > > >
> > > >>> > > > >
> > > >>> > > >
> > > >>> > >
> > > >>>
> > > >>
> >

[dmagda]

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 <[hidden email]> @Nikolay
Izhikov <[hidden email]> @Andrey Gura <[hidden email]> @Dmitriy
Pavlov <[hidden email]>

-
Denis


On Fri, Oct 30, 2020 at 1:12 PM Maxim Muzafarov <[hidden email]> 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 <[hidden email]> 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 <[hidden email]>
> 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 <[hidden email]>
> > > 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 <[hidden email]>:
> > > >
> > > > > 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 <
> > > [hidden email]> 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 <[hidden email]>
> 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 <
> [hidden email]>
> > > > >> 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 <
> > > [hidden email]>
> > > > >>> wrote:
> > > > >>> >
> > > > >>> > The Best way to require draft documentation with the proposed
> PR:)
> > > as a
> > > > >>> > part of TC check
> > > > >>> >
> > > > >>> > чт, 19 мар. 2020 г., 21:06 Denis Magda <[hidden email]>:
> > > > >>> >
> > > > >>> > > 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 <
> > > > >>> > > [hidden email]>
> > > > >>> > > 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 <
> > > [hidden email]>
> > > > >>> 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 <
> > > > >>> [hidden email]>
> > > > >>> > > > > 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 <
> > > [hidden email]
> > > > >>> >
> > > > >>> > > 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 <
> > > > >>> [hidden email]>
> > > > >>> > > > 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 <
> > > > >>> [hidden email]>
> > > > >>> > > > > 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
> > > > >>> > > > > > > >
> > > > >>> > > > > > >
> > > > >>> > > > > >
> > > > >>> > > > >
> > > > >>> > > >
> > > > >>> > >
> > > > >>>
> > > > >>
> > >
>