The discussions on the mailing list are important, but visual aids in mailing lists seem like they would be problematic.
Likewise, it has been noted in other threads that email clients can cause complications with discussion threading so that could raise issues with long-lived discussion topics. https://lists.apache.org/thread/sd9zxkqyj98f9mh49h3j1pgt7b935qrc I dislike the website discussion area idea as it seems to add a technical hurdle due to formatting. Unless I'm mistaken, any graphics or visual aids would be required to be located where website rendering code can load them and reference them into the page. Doesn't this mean that a contributor would be required to render the website locally to view all contextual information in order to view and comment accurately? Otherwise, the accumulo-website repo would need to allow changes to the design space to be committed and rendered publicly before review. That doesn't seem like an ideal solution. You could put all that information into a github issue with proper formatting in addition to the website file changes. However, this would mean that any sort of topic threading would result in per-line comments on files in that github issue and long-lived PR reviews. I could see this increasing notification counts in github and not being ideal. Overall, both options seem like a large amount of effort vs using a wiki (github or confluence based). I am a fan of using the github wiki for now until the cwiki creation is resolved. It unblocks progress and we can always pivot later. Have we confirmed with INFRA that the github wiki is not backed up? It is a git repo and able to be cloned locally, so backup is technically possible. On Thu, Mar 2, 2023 at 1:34 PM Dave Marion <dmario...@gmail.com> wrote: > I'm opposed to using the website for the reasons I specified earlier, so it > looks like we need to > wait for INFRA to fix Confluence. I'd be curious how much we need to use > the mailing list during > the design phase. We can announce meeting dates/times on the mailing list > and post links to > meeting notes in Confluence. Ultimately, decisions made by the people that > want to be involved > will turn into pull requests against the codebase which comitters can weigh > in on. When you say, > "... but decisions about those would still need to be done on the mailing > list." Are you saying that > we need to discuss every single design decision on the mailing list? > > On Thu, Mar 2, 2023 at 12:56 PM Christopher <ctubb...@apache.org> wrote: > > > So, I agree a space would be helpful. Although it's old school and > > inconvenient, the mailing list is the canonical place for discussion. > > We currently use GitHub issues a lot, but that's copied to a mailing > > list (as is our old JIRA space), so if people want to participate > > without a GitHub account, they can still do that. There are certain > > options that are perhaps less convenient, such as just using the > > mailing list and our dev SVN space, but still more appropriate than > > options that would be less ubiquitous for potential participants. > > > > I think the ASF Confluence is probably fine, for storing, editing, and > > collaborating on shared documents, but decisions about those would > > still need to be done on the mailing list. If I remember correctly, we > > used to have a Wiki space, prior to it being transferred to > > Confluence, but it was poorly maintained, so we abandoned it in favor > > of using the website for docs. I could be mis-remembering, but I think > > this is the case. It might explain why you can't create a Confluence > > space. > > > > My preference would be to just use the website. I think it's fine to > > have a dev / design area of the website, and we can discuss on GitHub > > issues for the accumulo-website repo. That is a bit less convenient > > than Confluence if it's used heavily, but it's more convenient in the > > sense that it's more accessible and fits more in line with our current > > mode of operation. Plus, when a document is final, it's easy to link > > to from our documentation, without making users jump to another > > service to view docs. > > > > I would be opposed to using GitHub wiki or a new git repo. We have > > enough repos. Although it seems like they are free, there is still a > > lot of boilerplate work to maintain them, from managing > > .github/workflows, .github/CONTRIBUTING.md, etc., to .asf.yaml, to > > README, to keeping copyright dates updated in the NOTICE file, and > > more. > > > > In summary, my preference: > > > > 1. Keep a space in accumulo-website, discuss on GH issues and mailing > > list (strongly preferred) > > 2. Confluence, discuss on mailing list (prefer over other options, but > > not a fan) > > 3. GitHub wiki, discuss on mailing list (strongly prefer not to use this > > option) > > 4. New GitHub repo, discuss on GH issues and mailing list (strongly > > prefer not to use this option) > > > > On Thu, Mar 2, 2023 at 12:30 PM Ed Coleman <edcole...@apache.org> wrote: > > > > > > Currently, asf cannot create new wiki's because of a Confluence issue ( > > https://issues.apache.org/jira/browse/INFRA-24291) I chatted with infra > > and in response they created that issue. > > > > > > To expand on this discussion, I would like to toss out another > > alternative to discuss / explore. What if we used a separate GitHub > > project, something like Accumulo-Design, just like accumulo-proxy and > > accumulo-examples. As a separate project, it would be available for > > collaboration for the community, but remain separate from main project > and > > the website to keep current code / documentation / design clearly > separate > > from speculative design discussions. As a project: > > > > > > - document history would be preserved with git commit history. > > > - document collaboration could be done with normal PR submissions / > > reviews. > > > - issues could be used to discuss design aspects, capturing the comment > > history. > > > > > > The biggest downside is that it would be yet another project to follow > / > > track. > > > > > > For me, I think the issue is that we need a public, collaborative space > > to hold design discussions. Neither the main project or the web-site seem > > quite appropriate and Confluence seems to lack the collaboration that can > > be achieved with github. > > > > > > We need a space to capture the redesign and whatever we select can be > > made to work - I'm just wondering what provides the easiest forum to > build > > a collaborative space for the Accumulo community. > > > > > > Ed Coleman > > > > > > > > > On 2023/02/28 16:35:31 dlmar...@comcast.net wrote: > > > > Circling back on this issue - I agree that comments and such make > > sense for internal design documents. I'm going to create an INFRA ticket > > for a cwiki space for Accumulo unless there are any objections. > > > > > > > > -----Original Message----- > > > > From: Drew Farris <d...@ill.org> > > > > Sent: Saturday, February 25, 2023 5:16 PM > > > > To: dev@accumulo.apache.org > > > > Subject: Re: [DISCUSS] Enable Github wiki in asf.yaml? > > > > > > > > As mentioned, wikis can provide a streamlined collaborative editing > > workflow that's less labor intensive than updating a website. They can > > promote collaboration by providing specific tooling to support comments, > > revisions and iteration. > > > > > > > > In terms of preservation, GH wikis act just like any other Git > > repository, with a remote at (for example) g...@github.com: > > apache/accumulo.wiki.git > > > > IIRC the pages are just GH flavored markdown. There are at least a > few > > Apache projects using them. > > > > > > > > However, GH wikis lack some features that I feel are important to > > support collaborative authoring. For example, the ability to comment and > > discuss specific passages in a document is a feature that's present in > > Cwiki, but not in GH wikis. I've come appreciate this this in my google > > docs and office workflows, so expect that it would be useful for Accumulo > > design discussions too. > > > > > > > > > > > > > > > > > > > > > > > > > > > > On Sat, Feb 25, 2023 at 2:54 PM Keith Turner <ktur...@apache.org> > > wrote: > > > > > > > > > I would like to try a wiki for design documents, I think it would > be > > > > > less cumbersome than the website and we can always link from the > > > > > website and issues to the wiki. I think its ok to give it a try > and > > > > > abandon it in the future, if abandoned would just need to properly > > > > > communicate that. The content should be archived in Apache > > > > > infrastructure, so if GH wiki does not do that then we should not > use > > > > > it. If GH wiki is not an option then could try cwiki. > > > > > > > > > > On Sat, Feb 25, 2023 at 7:55 AM <dlmar...@comcast.net> wrote: > > > > > > > > > > > > I reverted the change. I didn't think it would be a big deal, but > > if > > > > > > it > > > > > requires discussion, then let's discuss it. > > > > > > > > > > > > I'm looking for a place to host information related to internal > > > > > > design > > > > > discussions. I envision these to be living documents that will be > > > > > updated over time as the design/implementation progresses and that > > > > > other committers will be able to comment on and edit. I don't feel > > > > > that the website is the correct place for this because: > > > > > > > > > > > > 1. I don't think internal design discussions should go on the > > > > > > project > > > > > website. > > > > > > 2. Changes to the design documents could not be seen by others > > > > > > right > > > > > away (IIRC changes to the website are built and available at > > > > > https://accumulo.staged.apache.org/, but human intervention is > > > > > required to publish it at https://accumulo.apache.org/). > > > > > > > > > > > > I looked in the INFRA issues and other projects are using the GH > > > > > > Wiki > > > > > feature and I saw no mention of backing it up or the requirement to > > do > > > > > so (maybe they rely on GitHub backing it up?). It does appear that > we > > > > > would need an INFRA ticket so that they can modify the GitHub > project > > > > > settings to lock the GitHub wiki down so that only committers can > > > > > modify it. If GitHub Wiki is not acceptable, then I think Apache > > > > > Confluence ( > > > > > https://cwiki.apache.org) might be an acceptable alternative. > > > > > > > > > > > > -----Original Message----- > > > > > > From: Christopher <ctubb...@apache.org> > > > > > > Sent: Saturday, February 25, 2023 4:41 AM > > > > > > To: accumulo-dev <dev@accumulo.apache.org> > > > > > > Cc: comm...@accumulo.apache.org > > > > > > Subject: Re: [accumulo] branch main updated: Enable Github wiki > in > > > > > asf.yaml > > > > > > > > > > > > I don't recall a discussion about this change, but I think it > goes > > > > > against previous efforts to make the website the one canonical > > > > > location for our documentation. I don't even think infra is backing > > up > > > > > wiki repos, so there wouldn't even be a record of the wiki contents > > in > > > > > ASF spaces (vs. the main repo, which is backed up to GitBox and the > > > > > issue tracker, which CCs the notifications list). > > > > > > > > > > > > In short, I think this should be reverted and we should not use > the > > > > > GitHub wiki. If we need to store documents in a version controlled > > > > > way, we can store them on the website, or in our project's SVN dev > > > > > space. The wiki is just another place people would have to follow > if > > > > > they want to participate, and I don't think that serves us. > > Therefore, > > > > > I think we shouldn't use it. > > > > > > > > > > > > > > > > > > On Fri, Feb 24, 2023, 15:59 <dlmar...@apache.org> wrote: > > > > > > > > > > > > > This is an automated email from the ASF dual-hosted git > > repository. > > > > > > > > > > > > > > dlmarion pushed a commit to branch main in repository > > > > > > > https://gitbox.apache.org/repos/asf/accumulo.git > > > > > > > > > > > > > > > > > > > > > The following commit(s) were added to refs/heads/main by this > > push: > > > > > > > new ae8a817e7b Enable Github wiki in asf.yaml ae8a817e7b > is > > > > > > > described below > > > > > > > > > > > > > > commit ae8a817e7b2af8c64096ed1a4274eaef44c0e677 > > > > > > > Author: Dave Marion <dlmar...@apache.org> > > > > > > > AuthorDate: Fri Feb 24 15:59:10 2023 -0500 > > > > > > > > > > > > > > Enable Github wiki in asf.yaml > > > > > > > --- > > > > > > > .asf.yaml | 2 +- > > > > > > > 1 file changed, 1 insertion(+), 1 deletion(-) > > > > > > > > > > > > > > diff --git a/.asf.yaml b/.asf.yaml index bc2c943e82..08aa357082 > > > > > > > 100644 > > > > > > > --- a/.asf.yaml > > > > > > > +++ b/.asf.yaml > > > > > > > @@ -27,7 +27,7 @@ github: > > > > > > > - big-data > > > > > > > - hacktoberfest > > > > > > > features: > > > > > > > - wiki: false > > > > > > > + wiki: true > > > > > > > issues: true > > > > > > > projects: true > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
