20200505 Cassandra 4.0 Status Update
The board can be found here: https://issues.apache.org/jira/secure/RapidBoard.jspa?rapidView=355 [LHF] https://issues.apache.org/jira/secure/RapidBoard.jspa?rapidView=355=CASSANDRA=1661=1726=1658 [Tickets That Need Attention] https://issues.apache.org/jira/secure/RapidBoard.jspa?rapidView=355=CASSANDRA=1723=1719 We have 8 beta issues that are in the "Needs Attention" (stalled, needs reviewer) bucket. While not as pressing as the Alpha tickets, please raise a flag if you could use some help either on collaboration or on a review [Alpha Status] https://issues.apache.org/jira/secure/RapidBoard.jspa?rapidView=355=CASSANDRA=1723 We have 9 tickets not marked as 'done' for 4.0-alpha. 7 of them are related to flaky tests. Of the remaining I think one can be deferred to 4.0-beta and have pinged the reporter, which leaves just 2. (In Progress) CASSANDRA-15262 server_encryption_options is not backwards compatible with 3.11 (In Review) CASSANDRA-15674 liveDiskSpaceUsed and totalDiskSpaceUsed get corrupted if IndexSummaryRedistribution gets interrupted We are so close to being able to cut the first beta. [Beta Status] Referencing the above link, we have 15 bugs or tasks in beta. 8 of those are the Needs Attention referred to above and we have 6 that are backlogged in ToDo status. If you have tickets assigned to you that are flagged beta but don't currently have cycles to work on them, consider pinging in the #cassandra-dev channel on slack or hitting up the dev ML to see if there's anyone else with interest and cycles to help out there. [Needs Reviewer] https://issues.apache.org/jira/secure/RapidBoard.jspa?rapidView=355=CASSANDRA=detail=CASSANDRA-15560=1661=1659 Just one! A docs PR CASSANDRA-15749 Make clear in the documentation that stress is not a secured tool [Open vs. Closed Last 21 Days & Cumulative Flow] https://issues.apache.org/jira/secure/ConfigureReport.jspa?projectOrFilterId=filter-12348585=daily=21=true=major=12310865=com.atlassian.jira.jira-core-reports-plugin%3Acreatedvsresolved-report_token=A5KQ-2QAV-T4JA-FDED_9340412df581ebf97c07577c653b8288843dc555_lin=Next After a few weeks of closing more tickets than were opened, things are flattening off to closing about as many as we open. Nothing to be worried about, looks like reporting things that are being found and fixed. The Cumulative Flow Diagram: https://issues.apache.org/jira/secure/RapidBoard.jspa?rapidView=355=CASSANDRA=reporting=cumulativeFlowDiagram=939=936=931=1505=1506=1514=1509=1512=1507=2020-04-07=2020-04-28 [Icebergs] (copying from Josh last week as it's worth re-stating) There's 6 tickets in BLOCKED status in the rc release, all linked to the 40_Quality_Test epic, that I'm a little wary of. Those are probably our largest unidentified and unspecified scope outstanding to hitting a 4.0 GA, but they're also incredibly important for us to "do right" as a project in order to have 4.0 be a truly stable and production ready release. If you have a point of view on those tickets, please take a little time to share that PoV on there and help unstick them, since there are contributors available to be executing on those tests in parallel while we're executing on closing up our alpha and beta phases. Thanks for all the hard work through the least glamorous part of shipping... Jon. - To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org For additional commands, e-mail: dev-h...@cassandra.apache.org
Re: [DISCUSS] Documentation donation
> > usability and ease of consumption is just as important if not more as > correctness and coverage. I disagree pretty strongly with this. There is negative value in documentation that's incorrect and inaccurate. Much like comments or code: if it's wrong, I posit that nothing else matters. Honestly, if documentation were wrong it'd probably be better if it were impossible to find. :) Without the ability to locate information you want, correctness and > coverage are meaningless. This implies a binary situation which is, I believe, hyperbolic. I think it would be more accurate to say "The most correct and thorough documentation in the world can be completely hamstrung if it can't be navigated". All are important; we need correct, thorough, and easily navigable and usable documentation. But we also need a way to value different documentation frameworks against one another or we're going to get gridlocked in a vigorous airing of opinions where nobody changes their PoV and eventually whichever side is the most stubborn "wins", or the topic just rots on the vine, neither of which are healthy. On Mon, May 4, 2020 at 7:20 PM Paul Tepley wrote: > The order Josh mentions seems correct, but usability and ease of > consumption is just as important if not more as correctness and coverage. > > In technical writing, the key elements to usability and ease of > consumption are findability and searchability. Findability means finding > information for something you want to do without knowing what it is > beforehand. Searchability is finding information you know about using > the terms that you know. The key to effective documentation is that > information is both findable and searchable in "terms that the users know". > A simple example is gossip. If you know nothing about Cassandra, you > probably understand that nodes talk to each other, which you might search > for using "internode communication" or "network communication". > > Without the ability to locate information you want, correctness and > coverage are meaningless. > > Another principle that makes good documentation is that they are > solution-based. Two examples are replacing a node and adding a node. > > Another important feature of being able to produce accurate and complete > docs is the ability to reuse information. Using the previous examples, > replacing a node and adding a node, may have some of the same steps. > Reusing information is not saving time by writing only once, it's about > making sure that when information is updated, it's updated everywhere it > needs to be (especially in places you don't know about). Having a single > source for reusing information is essential to making this happen. > > Also, related to reusing information, the ability to pull from a central > location using includes/shortcodes/etc. can ease the testability and > findability of code examples used in documentation. Rather than scattering > code throughout the docs, you can store the code snippets in their own > repo. For instance, asciidoc has such a capability (amongst others): > > [source,ruby] > > include::example.rb[] > > > The last feature I want to mention that contributes to good documentation > is semantic structure. The idea of semantic structure is similar to > object-oriented programming, where objects contain data. So instead of > manually defining all the attributes of the warning, you can just declare > the warning and add the data. For example, suppose you want a warning that > says "Don't do this, it will kill your system!" In a non-semantics > authoring, such as Markdown (designed as format for writing for the web), > you'd have to define each element: > > **Warning** > Don't do this, it will kill your system! > > The problem here is not so much having to define each element but that a > different writer can do something different, such as vary the marking from > ** to *, as there is no enforced structure: > > *Warning* > Don't do this, it will kill your system! > > Although this is a very simple example, not being able to enforce a > standard can be confusing to the user because clues to using the > documentation lack consistency and refinement. > > In semantics-based documentation, such in reStructuredText, you can just > write > > . warning:: Don't do this, it will kill your system! > > and every instance will be consistent. > > I realize that everyone wants something simple that they don't have to > learn, but doing so will: > > 1) Decrease the efficiency of writing docs, which reduces the likelihood > of complete coverage. > 2) Reduce correctness, because the writer does not necessarily know > everywhere information needs to be updated. > 3) Diminish the usability and ease of consumption. For example, a lack of > consistency reduces the ability of the user to quickly scan a document for > the information they need and appears amateurish. > > On 2020/05/04 15:13:49, Joshua McKenzie wrote: > > I've been mulling over this topic the
Re: Staging website at cassandra.staged.apache.org
Hi Murukesh, That is a good question. To clarify, I meant that if we changed the site to be serviced from the 'asf-site' branch the master branch would be cleaner from that point forward. However, now that you mention it, I do like the idea of cleaning the entire master branch. Given that this alters the repository history, we might want to do such a change in a phased approach. e.g. 1. Change production site to be served from 'asf-site' branch. 2. Make a copy of the master branch called master_archive (or something similar) - this can be done sometime later after Step 1. 3. Clean master branch using bfg. 4. Keep the master_archive branch until we think it is no longer needed - we could keep the branch anywhere from a few days to a few years. Let me know what you think. Regards, Anthony On Fri, 1 May 2020 at 18:18, Murukesh Mohanan wrote: > For clarification, when you say "this would clean the master > branch history", would the content directory be removed from past commits > using bfg or similar tools? > > (I'm fine with either way; just curious.) > > On Fri, 1 May 2020, 07:12 Anthony Grasso, > wrote: > > > Hi everyone, > > > > Thanks to hard work by Mick every push to the cassandra-website *src/* > > directory in master is now automatically deployed to > > https://cassandra.staged.apache.org/. The automation is carried out by a > > Jenkins job at https://ci-cassandra.apache.org/job/cassandra-website/. > > This > > is really useful because it allows us to preview our changes in the > staging > > site before we push them to the production site! > > > > With the above change in place, the process to deploy a change to the > > production site is. > > 1. Commit your change to the *src/* directory in the master branch. > Jenkins > > will now automatically generate the (HTML) site pages in *content/* > > directory on the asf-staging branch. > > 2. Preview your changes on the staging site: > > https://cassandra.staged.apache.org/. > > 3. If the changes look good, then merge the *content/* directory on the > > asf-staging branch to the master branch using: > > > > > > $ git merge asf-staging > > $ git push > > > > > > An issue with the above process is the master branch history is now going > > to get polluted with the auto-generated content commits. Even without the > > Jenkins automation, the process to publish to the production site still > had > > the issue where commits to the master branch included both the *src/* and > > *content/* directory changes. A small one line change to the *src/* > > directory, could result in changes to hundreds of pages in the *content/* > > directory. > > > > Rather than serving the production site from the *content/* directory on > > the master branch, is there any objection to serving it from the asf-site > > branch? This would mean that the last step in the above process would be > > performed on the asf-site branch rather than the master branch. In > > addition, there would be no need to have a *content/* directory on the > > master branch. The *content/* directory from which the production site is > > served would live in the asf-site branch. This would clean the master > > branch history, hiding the generated *content/* directory and the > unwieldy > > content changes generated by Jenkins user. > > > > Let me know what you think about the proposed change. > > > > Regards, > > Anthony > > > > On Tue, 21 Apr 2020 at 16:40, Mick Semb Wever wrote: > > > > > For our cassandra-website repository, any changes to our website can > now > > > first be staged at https://cassandra.staged.apache.org/ > > > > > > The staged website comes from the content/ directory on the > `asf-staging` > > > branch. > > > > > > regards, > > > Mick > > > > > >
