Denis, Artem, I've marked the "tracing" ticket as important. Also, I've added a new section to the release page [1] and created documentation tickets for some features. Now there is a documentation ticket exists for each important feature implemented in 2.9. I know that some Igniters are currently working on documentation, but the question is still unanswered: where to push changes? To GitHub, or to readme.io? Guys, can you clarify, please?
[1]: https://cwiki.apache.org/confluence/display/IGNITE/Apache+Ignite+2.9#ApacheIgnite2.9-Documentationtasksforimportantfeaturesimplementedin2.9 вт, 4 авг. 2020 г. в 21:08, Denis Magda <[email protected]>: > Hi Alex, > > Certainly, the new documentation should not be treated as a showstopper, > and if the code is ready much earlier, then we can release the docs on > readme.io. > > But, it's not clear what's the documentation readiness status. As per our > updated release process, the docs need to be ready before the voting is > started [1]. That change was discussed and introduced after our > lessons-learned conversations related to the 2.8 release. > > Could you please help to figure out the status by preparing a list of > documentation tasks that must be completed before the voting time (all > significant features and changes)? The "most important tasks" section [2] > already lists most of them, but the list might be incomplete. For example, > the tracing feature should be added in 2.9, but it's not in the important > tasks list. There might be something else profound that we should put on > paper. > > Once we get the list, we can start working with the contributors in charge > to get things done. If some documentation pages won't be finished in 2 > weeks from now, then it's reasonable to contribute the 2.9 docs to the new > docs repository that will be ready for the release in 3-4 weeks. Just my > thinking. > > [1] > > https://cwiki.apache.org/confluence/display/IGNITE/Release+Process#ReleaseProcess-4.1EnsureDocumentationReadinessandAccouncementBlogPostActivity > [2] > > https://cwiki.apache.org/confluence/display/IGNITE/Apache+Ignite+2.9#ApacheIgnite2.9-Themostimportantreleasetasks > > - > Denis > > > On Tue, Aug 4, 2020 at 5:54 AM Alex Plehanov <[email protected]> > wrote: > > > Denis, > > > > We have some performance drop on benchmarks, so we need some time to find > > problematic commit and analyze it. I hope this will be completed during > the > > current week and we move to the "Vote preparation" phase to the start of > > next week. > > I think waiting for another month due to documentation it's too much. > > Do we have an option to release with documentation on readme.io and then > > move documentation in the new format during next month? > > > > > > > > пн, 3 авг. 2020 г. в 17:55, Denis Magda <[email protected]>: > > > > > I would wait for 3-4 weeks and release the new docs in 2.9. It means > that > > > the release should be announced the first week of September which is > not > > a > > > huge slip. Moreover, it feels like the testing phase and release > > procedures > > > will not be completed sooner. > > > > > > So, I would suggest contributing 2.9 related page to the new > > documentation > > > repository. > > > > > > > > > Denis > > > > > > On Monday, August 3, 2020, Artem Budnikov <[email protected] > > > > > wrote: > > > > > > > Hi Maxim, > > > > > > > > The new docs project is not finished yet. There are still a lot of > > pages > > > > to port to the new format, and we are still working on the > integration > > > with > > > > the web-site. Nevertheless, we can try to publish the Ignite 2.9 > > > > documentation on the web-site in the new format. The documentation > will > > > not > > > > be 100% complete, but it will be updated significantly and will > contain > > > > most of the information our users need. Actually, I would like to do > > > that, > > > > but it all depends on how much time I have before Ignite 2.9 is > > released. > > > > I'd say 2-3 weeks would be enough for me to finish all tasks that are > > > > critical for the publication. > > > > > > > > If we can wait with release 2.9 that much time, then I'll prepare the > > > > instruction on how to contribute to the docs. > > > > > > > > What do you think? > > > > > > > > -Artem > > > > > > > > On 03.08.2020 12:24, Maxim Muzafarov wrote: > > > > > > > >> Artem, > > > >> > > > >> I'd like to submit some documentation changes for 2.9 release. > Should > > > >> I update docs on readme.io or publish it on ignite.apache.org? > > > >> > > > >> On Wed, 29 Jul 2020 at 19:06, Artem Budnikov > > > >> <[email protected]> wrote: > > > >> > > > >>> Hi Alex, > > > >>> > > > >>> Sorry, I missed this message. There is still a lot of work on the > > docs. > > > >>> When is version 2.9 going to be released? > > > >>> > > > >>> -Artem > > > >>> > > > >>> On 22.07.2020 10:35, Alex Plehanov wrote: > > > >>> > > > >>>> Guys, > > > >>>> > > > >>>> What about documentation for 2.9 release? Are we going to publish > it > > > on > > > >>>> readme.io or publish it on ignite.apache.org? > > > >>>> What about new edits? Should we still edit pages on readme.io or > > > >>>> already > > > >>>> make changes in git repository? > > > >>>> Artem, could you please clarify the current documentation > workflow? > > > >>>> > > > >>>> > > > >>>> пн, 20 июл. 2020 г. в 16:42, Artem Budnikov < > > > >>>> [email protected]>: > > > >>>> > > > >>>> Denis, > > > >>>>> > > > >>>>> How about the next step of taking the HTML and committing it to > the > > > >>>>>> > > > >>>>> website > > > >>>>> > > > >>>>>> repository? Did you have a chance to think through this step? > > > >>>>>> > > > >>>>> Yes, I'll look into this this week. This shouldn't be very > > difficult. > > > >>>>> > > > >>>>> -Artem > > > >>>>> > > > >>>>> On 18.07.2020 00:43, Denis Magda wrote: > > > >>>>> > > > >>>>>> Worked out well on my end. Thanks for sending the update! > > > >>>>>> > > > >>>>>> How about the next step of taking the HTML and committing it to > > the > > > >>>>>> > > > >>>>> website > > > >>>>> > > > >>>>>> repository? Did you have a chance to think through this step? > > > >>>>>> > > > >>>>>> - > > > >>>>>> Denis > > > >>>>>> > > > >>>>>> > > > >>>>>> On Fri, Jul 17, 2020 at 5:27 AM Artem Budnikov < > > > >>>>>> > > > >>>>> [email protected]> > > > >>>>> > > > >>>>>> wrote: > > > >>>>>> > > > >>>>>> Hi everyone, > > > >>>>>>> > > > >>>>>>> I've prepared the initial set of source files for the Ignite > > > >>>>>>> documentation. If you are interested, you can take a look at > > > >>>>>>> https://github.com/apache/ignite/tree/IGNITE-7595/docs > > > >>>>>>> > > > >>>>>>> You can run a local web-server (jekyll) if you want to view the > > > docs > > > >>>>>>> in > > > >>>>>>> your browser. Refer to the README.adoc for instructions. Some > > > people > > > >>>>>>> had > > > >>>>>>> troubles installing Jekyll locally, so I added an instruction > on > > > how > > > >>>>>>> to > > > >>>>>>> use jekyll docker image. > > > >>>>>>> > > > >>>>>>> If you have any comments on the overall approach, please let me > > > know. > > > >>>>>>> The styles and content are still a work in progress, so please > > > don't > > > >>>>>>> report issues related to that. > > > >>>>>>> > > > >>>>>>> -Artem > > > >>>>>>> > > > >>>>>>> On 26.06.2020 01:54, Guru Stron wrote: > > > >>>>>>> > > > >>>>>>>> +1 for migrating docs to github. It will allow an easier > > > >>>>>>>> contribution > > > >>>>>>>> > > > >>>>>>> for > > > >>>>> > > > >>>>>> docs, I think. As a nice feature - adding an edit link (submit > PR > > > for > > > >>>>>>>> > > > >>>>>>> docs) > > > >>>>>>> > > > >>>>>>>> to the document page on site. > > > >>>>>>>> > > > >>>>>>>> As for keeping them separate - Microsoft keeps docs for it's > > > >>>>>>>> products > > > >>>>>>>> > > > >>>>>>> in > > > >>>>> > > > >>>>>> separate repos, for example. > > > >>>>>>>> > > > >>>>>>>> On Thu, 25 Jun 2020 at 15:48, Artem Budnikov < > > > >>>>>>>> > > > >>>>>>> [email protected]> > > > >>>>>>> > > > >>>>>>>> wrote: > > > >>>>>>>> > > > >>>>>>>> OK, let's give it a try. > > > >>>>>>>>> > > > >>>>>>>>> The way I see it, the documentation source files will be > > located > > > in > > > >>>>>>>>> > > > >>>>>>>> the > > > >>>>> > > > >>>>>> "/docs" folder, including UI templates/styles, asciidoc files, > and > > > >>>>>>>>> > > > >>>>>>>> build > > > >>>>> > > > >>>>>> scripts. I'll start experimenting with this and will let you > know > > > when > > > >>>>>>>>> basic setup is ready. > > > >>>>>>>>> > > > >>>>>>>>> -Artem > > > >>>>>>>>> > > > >>>>>>>>> On 23.06.2020 20:19, Denis Magda wrote: > > > >>>>>>>>> > > > >>>>>>>>>> I believe that by keeping the documentation sources in the > > same > > > >>>>>>>>>> > > > >>>>>>>>> repository > > > >>>>>>>>> > > > >>>>>>>>>> with the source code will help us to prepare and release all > > the > > > >>>>>>>>>> > > > >>>>>>>>> release > > > >>>>>>> > > > >>>>>>>> artifacts at the same time. So, +1 for hosting raw > documentation > > > >>>>>>>>>> > > > >>>>>>>>> ascii-doc > > > >>>>>>>>> > > > >>>>>>>>>> pages in the main Ignite repo. However, the HTML version > needs > > > to > > > >>>>>>>>>> > > > >>>>>>>>> reside > > > >>>>>>> > > > >>>>>>>> on > > > >>>>>>>>> > > > >>>>>>>>>> the Ignite website, which is similar to the API docs. We can > > > >>>>>>>>>> create > > > >>>>>>>>>> > > > >>>>>>>>> tools > > > >>>>>>> > > > >>>>>>>> to do this in one click. > > > >>>>>>>>>> > > > >>>>>>>>>> Post-reviews are not prohibited in Apache, quite the > opposite, > > > and > > > >>>>>>>>>> > > > >>>>>>>>> they > > > >>>>> > > > >>>>>> suit the documentation contribution process better. It's ok if > > > >>>>>>>>>> > > > >>>>>>>>> committers > > > >>>>>>> > > > >>>>>>>> to the documentation merge the changes first and ask for a > > review > > > >>>>>>>>>> > > > >>>>>>>>> later > > > >>>>> > > > >>>>>> if > > > >>>>>>>>> > > > >>>>>>>>>> needed. > > > >>>>>>>>>> > > > >>>>>>>>>> - > > > >>>>>>>>>> Denis > > > >>>>>>>>>> > > > >>>>>>>>>> > > > >>>>>>>>>> On Tue, Jun 23, 2020 at 6:53 AM Artem Budnikov < > > > >>>>>>>>>> > > > >>>>>>>>> [email protected]> > > > >>>>>>>>> > > > >>>>>>>>>> wrote: > > > >>>>>>>>>> > > > >>>>>>>>>> Pavel, > > > >>>>>>>>>>> > > > >>>>>>>>>>> I don't think so: we can't add snippets pointing to new > APIs > > > >>>>>>>>>>>> from a > > > >>>>>>>>>>>> separate repo, > > > >>>>>>>>>>>> > > > >>>>>>>>>>> Snippets are kept together with the docs, they /don't need/ > > to > > > be > > > >>>>>>>>>>> > > > >>>>>>>>>> stored > > > >>>>>>> > > > >>>>>>>> in the main repo, although they can. They are compilable and > up > > to > > > >>>>>>>>>>> > > > >>>>>>>>>> date. > > > >>>>>>> > > > >>>>>>>> I update the docs and API samples for features that hasn't > been > > > >>>>>>>>>>> > > > >>>>>>>>>> released > > > >>>>>>> > > > >>>>>>>> in the GridGain docs and never thought it was a problem. I > > > >>>>>>>>>>> > > > >>>>>>>>>> understand > > > >>>>> > > > >>>>>> that you don't want to do extra work when adding code samples, > but > > > >>>>>>>>>>> > > > >>>>>>>>>> it > > > >>>>> > > > >>>>>> looks like just an inconvenience. Let me suggest this: Let's > think > > > >>>>>>>>>>> > > > >>>>>>>>>> about > > > >>>>>>> > > > >>>>>>>> a solution that will be comfortable for you, I'm pretty sure > > this > > > >>>>>>>>>>> inconvenience can be solved technically. But I need time to > > > >>>>>>>>>>> think it > > > >>>>>>>>>>> through. > > > >>>>>>>>>>> > > > >>>>>>>>>>> we can't see the docs when doing global search (and/or > > replace) > > > >>>>>>>>>>>> > > > >>>>>>>>>>> from > > > >>>>> > > > >>>>>> the IDE. > > > >>>>>>>>>>>> > > > >>>>>>>>>>> I think you can add the docs repo to your IDE as a > project. I > > > >>>>>>>>>>> used > > > >>>>>>>>>>> > > > >>>>>>>>>> to > > > >>>>> > > > >>>>>> do > > > >>>>>>> > > > >>>>>>>> it in the beginning but then switched to Sublime Text, because > > > it's > > > >>>>>>>>>>> > > > >>>>>>>>>> more > > > >>>>>>> > > > >>>>>>>> convenient to me. We are looking at it from different > > > perspectives. > > > >>>>>>>>>>> > > > >>>>>>>>>> I'm > > > >>>>>>> > > > >>>>>>>> trying to create a process that is comfortable for tech > writers > > > >>>>>>>>>>> > > > >>>>>>>>>> rather > > > >>>>> > > > >>>>>> than developers. And everybody has to accept some kind of a > > > >>>>>>>>>>> > > > >>>>>>>>>> compromise:) > > > >>>>>>> > > > >>>>>>>> Well, no one is able to "freely" commit code to Apache master, > > > >>>>>>>>>>>>> > > > >>>>>>>>>>>> there > > > >>>>> > > > >>>>>> is a process to follow - CI, reviews, etc. > > > >>>>>>>>>>>>> Same should happen for the docs, separate repo or not. > > > >>>>>>>>>>>>> But a separate repo will require separate > > > ownership/management > > > >>>>>>>>>>>>> (probably?), > > > >>>>>>>>>>>>> but we already have everything in the main repo, why > > > introduce > > > >>>>>>>>>>>>> > > > >>>>>>>>>>>> overhead? > > > >>>>>>>>> > > > >>>>>>>>>> Just think about it from my perspective. That creates a > HUUUGE > > > >>>>>>>>>>> > > > >>>>>>>>>> overhead > > > >>>>>>> > > > >>>>>>>> for technical writers who work on the docs, and they are the > > ones > > > >>>>>>>>>>> > > > >>>>>>>>>> who > > > >>>>> > > > >>>>>> provide 90% of updates. I agree about the review process, and > I'm > > > >>>>>>>>>>> > > > >>>>>>>>>> going > > > >>>>>>> > > > >>>>>>>> to think it over. But now it seems that we don't have to > impose > > > any > > > >>>>>>>>>>> strict process that impedes preparation of the docs. > > > >>>>>>>>>>> > > > >>>>>>>>>>> -Artem > > > >>>>>>>>>>> > > > >>>>>>>>>>> > > > >>>>>>>>>>> On 23.06.2020 15:35, Pavel Tupitsyn wrote: > > > >>>>>>>>>>> > > > >>>>>>>>>>>> all your pros points work just as well for a separate > > > repository > > > >>>>>>>>>>>>> > > > >>>>>>>>>>>> I don't think so: we can't add snippets pointing to new > APIs > > > >>>>>>>>>>>> from a > > > >>>>>>>>>>>> separate repo, > > > >>>>>>>>>>>> we can't see the docs when doing global search (and/or > > > replace) > > > >>>>>>>>>>>> > > > >>>>>>>>>>> from > > > >>>>> > > > >>>>>> the IDE. > > > >>>>>>>>>>>> > > > >>>>>>>>>>>> I am able to freely commit to master > > > >>>>>>>>>>>>> > > > >>>>>>>>>>>> Well, no one is able to "freely" commit code to Apache > > master, > > > >>>>>>>>>>>> > > > >>>>>>>>>>> there > > > >>>>> > > > >>>>>> is a process to follow - CI, reviews, etc. > > > >>>>>>>>>>>> Same should happen for the docs, separate repo or not. > > > >>>>>>>>>>>> But a separate repo will require separate > > ownership/management > > > >>>>>>>>>>>> (probably?), > > > >>>>>>>>>>>> but we already have everything in the main repo, why > > introduce > > > >>>>>>>>>>>> > > > >>>>>>>>>>> overhead? > > > >>>>>>>>> > > > >>>>>>>>>> On Tue, Jun 23, 2020 at 2:59 PM Artem Budnikov > > > >>>>>>>>>>>> <[email protected] <mailto: > a.budnikov.ignite@gmai > > > >>>>>>>>>>>> l.com>> > > > >>>>>>>>>>>> > > > >>>>>>>>>>> wrote: > > > >>>>>>>>>>> > > > >>>>>>>>>>>> Pavel, > > > >>>>>>>>>>>> > > > >>>>>>>>>>>> As far as I can see, all your pros points work > just > > > as > > > >>>>>>>>>>>> well > > > >>>>>>>>>>>> > > > >>>>>>>>>>> for a > > > >>>>>>> > > > >>>>>>>> separate repository (except for "everybody knows > about > > > >>>>>>>>>>>> > > > >>>>>>>>>>> it"). I > > > >>>>> > > > >>>>>> don't > > > >>>>>>>>> > > > >>>>>>>>>> mind keeping the docs in Ignite repo as long as I > am > > > >>>>>>>>>>>> able to > > > >>>>>>>>>>>> > > > >>>>>>>>>>> freely > > > >>>>>>>>> > > > >>>>>>>>>> commit to master. Will I be able to do that? > > > >>>>>>>>>>>> > > > >>>>>>>>>>>> -Artem > > > >>>>>>>>>>>> > > > >>>>>>>>>>>> On 23.06.2020 14:04, Pavel Tupitsyn wrote: > > > >>>>>>>>>>>> > Ilya, Artem, > > > >>>>>>>>>>>> > > > > >>>>>>>>>>>> > "Separate repo just because we can't finish > docs > > > >>>>>>>>>>>> before > > > >>>>>>>>>>>> > > > >>>>>>>>>>> release" > > > >>>>>>> > > > >>>>>>>> > does not make sense to me. My proposal is: > > > >>>>>>>>>>>> > > > > >>>>>>>>>>>> > - Working version is in the master branch > > > >>>>>>>>>>>> > - When a release branch is created, e.g. > > > ignite-2.9, > > > >>>>>>>>>>>> we > > > >>>>>>>>>>>> > > > >>>>>>>>>>> create > > > >>>>>>> > > > >>>>>>>> > ignite-2.9-docs and update it as long as we want. > > > >>>>>>>>>>>> > > > > >>>>>>>>>>>> > Pros (compared to a separate repo): > > > >>>>>>>>>>>> > - Docs can be updated along with the code, same > > > >>>>>>>>>>>> review > > > >>>>>>>>>>>> > > > >>>>>>>>>>> process > > > >>>>>>> > > > >>>>>>>> > - Visibility - everyone knows about main repo, docs > > are > > > >>>>>>>>>>>> searchable together > > > >>>>>>>>>>>> > with code in the IDE > > > >>>>>>>>>>>> > - Code snippets can reference the actual code > and > > > we > > > >>>>>>>>>>>> make > > > >>>>>>>>>>>> > > > >>>>>>>>>>> sure > > > >>>>>>> > > > >>>>>>>> they compile > > > >>>>>>>>>>>> > - Code snippets can be tested on TC > > > >>>>>>>>>>>> > > > > >>>>>>>>>>>> > GridGain uses a separate repo for their docs, > and > > > it > > > >>>>>>>>>>>> > > > >>>>>>>>>>> proved > > > >>>>> > > > >>>>>> to > > > >>>>>>> > > > >>>>>>>> be less than > > > >>>>>>>>>>>> > optimal. > > > >>>>>>>>>>>> > Especially when adding samples for new APIs > which > > > >>>>>>>>>>>> are not > > > >>>>>>>>>>>> > > > >>>>>>>>>>> yet > > > >>>>> > > > >>>>>> released. > > > >>>>>>>>>>>> > > > > >>>>>>>>>>>> > > > > >>>>>>>>>>>> > > > > >>>>>>>>>>>> > On Tue, Jun 23, 2020 at 1:19 PM Artem Budnikov > > > >>>>>>>>>>>> <[email protected] <mailto: > > > >>>>>>>>>>>> > > > >>>>>>>>>>> [email protected] > > > >>>>>>> > > > >>>>>>>> > wrote: > > > >>>>>>>>>>>> > > > > >>>>>>>>>>>> >> Pavel, > > > >>>>>>>>>>>> >> > > > >>>>>>>>>>>> >> Yes, I mean a separate repository. The reason > is > > > >>>>>>>>>>>> that > > > >>>>>>>>>>>> documentation is > > > >>>>>>>>>>>> >> usually updated after the product version is > > > >>>>>>>>>>>> released. As > > > >>>>>>>>>>>> > > > >>>>>>>>>>> Ilya > > > >>>>>>> > > > >>>>>>>> pointed > > > >>>>>>>>>>>> >> out, keeping the docs in the main Ignite > > > repository > > > >>>>>>>>>>>> would > > > >>>>>>>>>>>> > > > >>>>>>>>>>> entail > > > >>>>>>>>> > > > >>>>>>>>>> >> completing the docs before the release date, > which > > > is > > > >>>>>>>>>>>> not > > > >>>>>>>>>>>> possible under > > > >>>>>>>>>>>> >> current circumstances. > > > >>>>>>>>>>>> >> > > > >>>>>>>>>>>> >> Ilya, > > > >>>>>>>>>>>> >> > > > >>>>>>>>>>>> >> You can look at your company's documentation > > for a > > > >>>>>>>>>>>> > > > >>>>>>>>>>> working > > > >>>>> > > > >>>>>> prototype > > > >>>>>>>>>>>> >> turned production-ready approach. The approach > > has > > > >>>>>>>>>>>> been > > > >>>>>>>>>>>> > > > >>>>>>>>>>> tested > > > >>>>>>> > > > >>>>>>>> for a > > > >>>>>>>>>>>> >> while and proved to be successful, at least > with > > > >>>>>>>>>>>> respect > > > >>>>>>>>>>>> > > > >>>>>>>>>>> to > > > >>>>> > > > >>>>>> our > > > >>>>>>> > > > >>>>>>>> goals here. > > > >>>>>>>>>>>> >> > > > >>>>>>>>>>>> >> -Artem > > > >>>>>>>>>>>> >> > > > >>>>>>>>>>>> >> On 23.06.2020 12:48, Ilya Kasnacheev wrote: > > > >>>>>>>>>>>> >>> Hello! > > > >>>>>>>>>>>> >>> > > > >>>>>>>>>>>> >>> I'm not really sold on the github version > yet, > > I > > > >>>>>>>>>>>> would > > > >>>>>>>>>>>> > > > >>>>>>>>>>> like to > > > >>>>>>> > > > >>>>>>>> see a > > > >>>>>>>>>>>> >>> prototype of such documentation before > > deciding, > > > >>>>>>>>>>>> so for > > > >>>>>>>>>>>> > > > >>>>>>>>>>> me > > > >>>>> > > > >>>>>> it'w > > > >>>>>>>>> > > > >>>>>>>>>> >>> 0 > > > >>>>>>>>>>>> >>> > > > >>>>>>>>>>>> >>> Pavel, we don't have enough discipline to > make > > > >>>>>>>>>>>> sure that > > > >>>>>>>>>>>> > > > >>>>>>>>>>> all > > > >>>>>>> > > > >>>>>>>> >> documentation > > > >>>>>>>>>>>> >>> is ready at the time of release, and we may > > need > > > >>>>>>>>>>>> to add > > > >>>>>>>>>>>> notices here and > > > >>>>>>>>>>>> >>> there after a release is already out. This > > means, > > > >>>>>>>>>>>> > > > >>>>>>>>>>> separate > > > >>>>> > > > >>>>>> git > > > >>>>>>> > > > >>>>>>>> >> repository, > > > >>>>>>>>>>>> >>> or at least separate git tag on that > > repository, > > > is > > > >>>>>>>>>>>> > > > >>>>>>>>>>> needed. > > > >>>>> > > > >>>>>> >>> > > > >>>>>>>>>>>> >>> Regards, > > > >>>>>>>>>>>> > > > >>>>>>>>>>>> > > > > > > -- > > > - > > > Denis > > > > > >
