You can track that issue at https://issues.apache.org/jira/browse/INFRA-24291
On Fri, Mar 3, 2023 at 10:31 AM Dave Marion <dmario...@gmail.com> wrote: > > Ed, > > Any update from INFRA on being able to create confluence pages? > > On Thu, Mar 2, 2023 at 4:07 PM Christopher <ctubb...@apache.org> wrote: > > > We've definitely used the website for more than that. We use it to > > document things for users, help developers know how to contribute, > > store drafts of designs, share user stories via blogs, do release > > announcements, and more. There's definitely space on the website to do > > this kind of thing, if we want to. We've used it that way before. If > > you only see it as a place "for user consumption after everything has > > been finalized", then you're missing out on the other ways we > > currently use the site, and the ways we've used it in the past. > > > > With the website, most of the collaboration would happen in the GH > > issues about proposed designs or changes to designs, just like we do > > today with code or other documentation, which everybody is used to. I > > agree it's not as good as Google Docs for on-the-fly > > comments/annotations, but I don't think Confluence or Wiki are as good > > as that either, and Google Docs isn't really an option... unless you > > just want to link to it in the mailing list and stick to Google Docs > > from your personal Google account, until it's ready for publication, > > which would also be fine (any interested persons can simply request > > write access by replying to the message where you shared the link).. > > > > We are a much smaller project than many others, and we have previously > > suffered from having stuff too spread out. Even if other projects find > > a separate space valuable for them, I'm not sure it's best for the > > Accumulo project. While I think it's useful to examine what other > > projects do, I do think we should be careful to adopt anything just > > because others find it convenient for them. > > > > Confluence is my second choice, but with a big gap between it and my > > first choice. > > > > On a personal note: I hate using Confluence, because I think the > > navigation is highly unintuitive, as is the permissions model, and I > > don't like the idea of learning yet another wiki-syntax (though I've > > read Confluence supports some limited Markdown, but probably not the > > same as GitHub/Jekyll). I also do not want to set up custom > > notifications for watching yet another space. If we use Confluence, I > > will probably contribute very infrequently there because of my > > frustrations with having used it before. However, that would be my > > choice, and should not be a reason the project chooses one over > > another. I'm sharing my personal opinion only because it is > > influencing my opinion about the website being more accessible, via > > our current GitHub PR/issue/Markdown workflows, and I wonder how many > > other potential contributors would feel similarly. It's hard to know, > > since it seems like a lot of this is subjective, and is going to come > > down to a consensus of personal preferences. > > > > On Thu, Mar 2, 2023 at 3:46 PM Dave Marion <dmario...@gmail.com> wrote: > > > > > > I don't see the website as an area where we would have collaborative > > > discussions about an idea. For example, making comments and suggestions > > on > > > a document like you can do in Google Docs. I see the website as a place > > > where items are documented for user consumption after everything has been > > > finalized. I'm not trying to create a private discussion area, I think > > > anyone can see the wiki (but I think anonymous comments are disabled due > > to > > > spam issues). I see no issue with putting work-in-progress documents on a > > > wiki and referencing them via emails to the dev list. I think this is > > done > > > in a lot of other projects. Non-committers that don't have access to the > > > wiki and want to make comments, suggestions, and ask questions can do so > > > via the mailing list. I think it's also possible that people can get > > > confluence accounts (see > > https://issues.apache.org/jira/browse/INFRA-7058), > > > so if a non-committer wanted to participate they could. > > > > > > On Thu, Mar 2, 2023 at 2:53 PM Christopher <ctubb...@apache.org> wrote: > > > > > > > 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 > > > > > > > > Your reasons that I saw were: > > > > > > > > > 1. I don't think internal design discussions should go on the project > > > > website. > > > > > > > > That doesn't look to me like a reason. That appears to just be stating > > > > the conclusion. Did I miss your reason here? > > > > > > > > > 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/). > > > > > > > > What do you mean by "others" here? Do you mean "users", as opposed to > > > > "developers/contributors"? The ASF draws a distinction between > > > > "developers/contributors" and "users" as it pertains to official > > > > releases. Releases are intended to be consumed by users, and > > > > pre-release stuff is intended to be collaborative, open to all > > > > potential developers/contributors. Very very rarely are things > > > > reserved exclusively for committers. We don't even have a private > > > > committers space (the private mailing list is PMC-private, not > > > > committer-private). Having a distinction between users and developers > > > > doesn't mean we can't publish things on the website... it just means > > > > that we should be careful about how we do it, which is the same care > > > > we should take regardless of where we put it. Specifically, the care > > > > we need to take is to avoid marketing pre-release content to users. > > > > One way we can exercise this care for content on our website is that > > > > we can avoid sharing these unpolished designs by simply not linking > > > > them on the site, or by placing them in an area that is clearly marked > > > > as intended for devs. But, we have no similar distinction between > > > > committers and non-committer devs for which we should avoid sharing > > > > pre-release content under development. In fact, it is the opposite... > > > > we should be developing openly so as to allow room for non-committers > > > > to become committers through participation in development activities. > > > > > > > > As for the staging/publication of the website, that's just a mechanic > > > > for verifying the website isn't broken before we serve it. It's not a > > > > mechanism for keeping things internal vs. shared and doesn't have > > > > anything to do with the separation between devs and users. We already > > > > publish Draft contents to the website, as well as developer-specific > > > > documentation not intended for users. > > > > > > > > We've even specifically published work-in-progress design documents > > > > there, of the same type that seems to be the basis of this > > > > conversation (https://accumulo.apache.org/design/system-snapshot). I > > > > would strongly prefer us to continue to do it this way, rather than > > > > create a new space, and have these kinds of things scattered in > > > > multiple places. > > > > > > > > If, on the other hand, you intend to say that these should be private > > > > because they aren't ready for other potential contributors, then I > > > > would argue that we're an openly developed project... if something > > > > isn't ready to be shared with other potential contributors / > > > > developers, such that you want to keep it internal to existing > > > > committers, then it's not ready to be contributed to the project at > > > > all... because we don't restrict collaboration to only existing > > > > committers. That would prevent others from participating and earning > > > > the merit to become committers, and that's not something we should be > > > > doing. Anything that is okay to share with existing committers should > > > > be okay to share to other potential contributors who want to > > > > participate, and should be done in a space that allows them to do > > > > that. The website is a perfect space for that, and has everything we > > > > need. I'm actually not sure about Confluence... I suspect > > > > non-committers wouldn't be able to participate there because they > > > > probably can't get accounts for 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? > > > > > > > > Yes and no. I am saying that decisions need to happen on the mailing > > > > list, but I agree with you that this can be satisfied through pull > > > > requests. I just wanted to emphasize that regardless of where we do > > > > that pre-decision collaboration, that collaboration should not be > > > > misconstrued as a decision to accept those ideas into the project. The > > > > decision occurs during the PR or other activity that interfaces with > > > > the mailing list, subsequent to the collaboration in the design/idea > > > > phase. > > > > > > > > As for the pre-decision collaboration space we're discussing, I just > > > > want to be careful that we're not creating such a space in an > > > > exclusionary way that allows only existing committers to participate, > > > > that excludes other potential contributors. This is still an > > > > openly-developed project, and we should collaborate in a space that is > > > > not exclusive to existing committers, but open to non-committer > > > > contributors and potential contributors as well. So, while we may want > > > > to keep a line separating dev activity from user consumption (an > > > > important separation that relates to official ASF releases), we should > > > > not be drawing a line between committer-devs as "internal" and > > > > contributor-devs as "external". The website, with its own issue > > > > tracker, the ability to render markdown, do reviews, and > > > > collaboratively edit, seems like the ideal place to me. We've used it > > > > before for the same purpose, and I think we should continue to do so. > > > > > > > > > > > > > > > > > > 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 > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
