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

Reply via email to