> Currently this is shared in the docs folder in the ozone repo. Maybe you already talked about this, but once we move the docs content to the ozone-site repo (afaik that’s the plan) we will share these there, right? Will we have them published to the site?
Thanks for bringing this up Zita, I haven't thought about this part yet but we can discuss it when it comes time to move/remove the existing docs. My initial thought would be to keep design docs checked in with the code, not the website. The new "System Internals" section of the documentation is a more user friendly place to document the technical side of features once they are released. IMO just dropping a design doc that has not been updated since the feature's brainstorming phase on the website is not a substitute for proper technical documentation of a finished feature, but unfortunately the "design docs" section of the current site makes this common practice. That's probably a discussion for a different thread though. I'm +1 for re-examining the categories in GH discussions since it sounds like we will be using that more based on feedback in this thread so far. Again maybe we can get into specifics on a separate thread (or a meta-discussion in GH discussions) where we could try some new ideas. Ethan On Thu, Feb 1, 2024 at 7:14 AM Zita Dombi <zitado...@apache.org> wrote: > Thanks for bringing this up! I agree with the ideas shared above. The way > you shared the design proposal for container reconciliation is really good, > it’s easy to give feedback and later to track back why some decisions were > made. Currently this is shared in the docs folder in the ozone repo. Maybe > you already talked about this, but once we move the docs content to the > ozone-site repo (afaik that’s the plan) we will share these there, right? > Will we have them published to the site? I agree to share these kinds of > proposals on the mailing list as well, so everyone is aware of it. > > I know that the mailing list is ideal for every kind of communication > inside the community, but to be honest, for me it’d be “hard” (maybe > uncomfortable is a better word) to send an email with a smaller technical > question to the whole community, I don’t know if others feel this way too. > I completely agree with this from Ethan: “*For the dev@ list, I think high > level updates like releases, new feature proposals, feature branch merges, > or major project milestones make sense there, since it gives people insight > as to which Jiras or PRs to follow.*” I believe Github discussions can be > used (of course the mailing list too) for all the other things that do not > necessarily require attention/action from everyone in the community. > > I’d like to suggest rethinking the categories inside our Github > discussions. Currently we have these (most of them are default): > > - Announcements > - Community Sync Meetings > - FAQ > - General > - Ideas > - Polls > - Show and tell > > Maybe we could adjust these more to the project and we can add sections too > (“To further organize your discussions, you can create sections and then > nest your categories within a section.” > > https://docs.github.com/en/discussions/managing-discussions-for-your-community/managing-categories-for-discussions > ). > > > - I’m not sure what should be the difference between *General* and > *FAQ*, > I think currently both of them have similar questions (but eg. in > *General* you can't mark a discussion as answered). Any kind of category > (or section) we will have for the questions (from users/developers), it > could have sub-categories, like technical questions, operational > questions, > etc. > - What do you think, do *Polls* make sense there? As far as I know, > votes in the community should happen in the mailing list. > - We can add a more accurate description for the categories, so new > contributors can navigate better too. > > I found a good example to see what more discussion categories look like: > https://github.com/orgs/community/discussions. It'd be great to hear other > ideas, how to manage our Github discussions :) > > Regards, > Zita > > István Fajth <fapi...@gmail.com> ezt írta (időpont: 2024. febr. 1., Cs, > 11:02): > > > I tend to think that discussing design documents is absolutely fine in > PRs > > and that they should be held alongside with the project. I see the > benefit > > of possibly more effort going into keeping it up to date if it lives with > > the codebase. > > Still I welcome the suggestion from Ethan, to have an emphasis on at > least > > notifying everyone in the dev@ list also, so who is interested can chime > > in > > to the design process. > > If we select to go this way, leave slack, move user/operational questions > > to Github Discussions and design to PRs with a notification to the dev@ > > list, I am +1 for this approach, but I think we are still open to > > further discussion and ideas before we close this thread and take action, > > so I encourage others to chime in ;) > > > > Cheers, > > Pifta > > > > Ethan Rose <er...@apache.org> ezt írta (időpont: 2024. febr. 1., Cs, > > 0:29): > > > > > Thanks for bringing up this proposal Ritesh. I am +1 for using GitHub > > > Discussions for user/operational questions and indicating that on our > > Slack > > > channel. > > > > > > I am also +1 for design discussions happening as PRs to markdown > > documents > > > as we are doing for container reconciliation. Inline comments make it > > > easier to track and resolve threads instead of one global conversation > > > chain for the entire feature that inevitably gets sidetracked and > > people’s > > > points not addressed. Jira discussions for design proposals also lack > > > threading and have this same problem. An email to dev@ pointing to the > > > design proposal PR would still be good since not everyone may be > watching > > > every new PR that comes in. > > > > > > I agree with Pifta’s comment that GitHub discussions are easier to find > > and > > > use than the users@ mailing list for most people. I think our users > > share > > > this opinion since both options are available but people only choose to > > > submit questions to GitHub discussions. Favoring the more popular > option > > > seems better for community engagement. > > > > > > For the dev@ list, I think high level updates like releases, new > feature > > > proposals, feature branch merges, or major project milestones make > sense > > > there, since it gives people insight as to which Jiras or PRs to > follow. > > > Then people can subscribe to the threads they want on Jira or GitHub > > > without the entire dev base being blasted for niche feature specific > > issues > > > (of which we have many). I will admit I’ve been an exception to this by > > > sending dev@ with periodic updates about the new website, but I think > at > > > this stage the updates are still “Project Wide” and the new website is > > > something that should remain on everyone’s radar. > > > > > > Speaking of the website, once we decide which communication channels > are > > > favored for what purpose we can fill in the communication channels > > > < > > https://ozone-site-v2.staged.apache.org/community/communication-channels > > > > > page on the new site to indicate this. We can also revisit our > preferred > > > method(s) for design proposals > > > < > > > > > > https://ozone.apache.org/docs/1.4.0/design/ozone-enhancement-proposals.html > > > > > > > and update this documentation on the new site’s Developer Guide as > well. > > > > > > On Wed, Jan 31, 2024 at 9:57 AM Ritesh Shukla > > <rit...@cloudera.com.invalid > > > > > > > wrote: > > > > > > > Hi Pifta, > > > > > > > > Thank you for chiming in. > > > > > > > > I have actually not considered how to revive the mailing list for > > > > technical and design discussions. > > > > I am not sure why mailing lists are no longer as popular, in general > I > > > see > > > > a decline of > > > > using emails for discussions other than formal one way communication. > > > > > > > > I agree that the mailing list has more control over the data shared > vs. > > > > hosting it on Github. > > > > > > > > Github Discussions do have lower friction than switching to email to > > > > discuss. > > > > > > > > For design my personal preference is markdown and PRs > > > > Example: https://github.com/apache/ozone/pull/6121 > > > > This is something I insisted we do for the container reconciliation > > > design. > > > > > > > > One other aspect I wanted to bring up, there are many new > contributors > > > from > > > > China and China has its own eco system of messaging and chat apps > > > > where the community interacts. I would like to hear from them as well > > > > for a suitable approach to keep discussions out in the open > > > > and not behind closed walls of apps such as Slack or Weibo. > > > > > > > > In the note we leave in Slack and other documentation we can > encourage > > > > both mailing lists > > > > as well as Github Discussions. > > > > > > > > Regards, > > > > Ritesh > > > > > > > > > > > > > On Jan 31, 2024, at 9:31 AM, István Fajth <fapi...@gmail.com> > wrote: > > > > > > > > > > Hi Ritesh, > > > > > > > > > > thank you for the proposal, and taking action during the last > > community > > > > > sync. > > > > > I support the idea of using GitHub Discussions, but I would like to > > > bring > > > > > up one thing with GH Discussions. I am not a fan of Slack either > and > > I > > > > > agree Slack is far from optimal and is hard to search. > > > > > > > > > > It did not happen with Ozone, but as I remember there were projects > > > that > > > > > have been migrated to github and before that they were running in a > > > > > different system, this makes me skeptical, as it might happen in > the > > > > future > > > > > also. > > > > > So I would like to add one more thing to the table, mailing lists > > will > > > > > remain with us (as they are within the control of the foundation), > > and > > > > are > > > > > also indexed by search engines. > > > > > > > > > > In my opinion to move the operational problems and questions to > > github > > > > > discussions is definitely ok, as I see the value of having a > > dedicated > > > > > place where user centric questions are collected and discussed. > > > > > In the meantime I think we should promote the dev@ list for > > technical > > > > > discussions that are about design, code, or for any other topic > that > > > > > really is affecting mainly the developer community. > > > > > > > > > > Looking at our @dev mailing list, it is pretty silent recently even > > > > though > > > > > we are working on stabilization, performance, and features. (I > myself > > > am > > > > > also guilty and silent, I realized and would like to change that, > > > instead > > > > > of just doing things within JIRA and PRs.) > > > > > > > > > > So I am absolutely +1 for using github discussions in favor of > Slack > > > for > > > > > user/operational problems, I think it is more engaging than the > user@ > > > > list > > > > > for operational questions and can be our place to help out those > > > members > > > > of > > > > > the community who use Ozone, but I would still use the dev@ > mailing > > > list > > > > > for technical/design discussions and any other developer related > > > > > discussions/decisions as that remains within Apache, and for us it > > can > > > > > become a place where we can look for specific information. > > > > > This is my preference of course, but I felt it important to > > emphasise, > > > as > > > > > from your mail it is not clear for me if/what is our plan with the > > > > mailing > > > > > list usage, as discussions and slack are probably both a > contributing > > > > > factor to the relative silence of the mailing lists. > > > > > > > > > > Regards, > > > > > Pifta > > > > > > > > > > Kernel Time <kernelt...@gmail.com> ezt írta (időpont: 2024. jan. > > 30., > > > K, > > > > > 23:01): > > > > > > > > > >> We started using https://github.com/apache/ozone/discussions from > > May > > > > 2023 > > > > >> and this has been a good place for developers to reach out to the > > > > community > > > > >> as well as for the community to post ongoing progress. > > > > >> > > > > >> Pros for GitHub Discussions: > > > > >> 1. GitHub Discussions have less friction than Slack and are > cheaper > > > for > > > > >> Apache Org. Users only need a GitHub account. > > > > >> 2. GitHub Discussions are indexed by Google. Ref: > > > > >> > > > > >> > > > > > > > > > > https://www.google.com/search?q=apache+Cleaning+up+missing+containers+on+Ozone > > > > >> 3. GitHub Discussions can be organized, labelled > > > > >> 4. Github Discussion threads tend to be kept alive for a longer > > > duration > > > > >> than what Slack messages tend to be (anecdotally). > > > > >> > > > > >> Pros for Slack: > > > > >> 1. Slack is more real time than GitHub > > > > >> 2. Slack notifications are better than GitHub on mobile devices. > > > > >> > > > > >> I would like to propose that we deprecate Slack for technical > > > > discussions > > > > >> and move them to GitHub Discussions. > > > > >> > > > > >> What does this mean? > > > > >> 1. We will not shut down slack channel > > > > >> 1.1 Use the Slack channel for urgent non technical needs or > > casual > > > > >> conversations. > > > > >> 2. Any technical discussion initiated will be encouraged to be > moved > > > to > > > > >> Github Discussions. > > > > >> 3. We will remove documentation encouraging users to engage on > Slack > > > and > > > > >> instead make sure GitHub Discussions are encouraged. > > > > >> 4. We will add to the Slack channel a note encouraging developers > to > > > use > > > > >> GitHub Discussions. > > > > >> > > > > >> Please let me know what you think. > > > > >> I plan to make the change in around 15-30 days if the majority of > > > > >> developers feel this is a cleaner approach to engage with the > > > community. > > > > >> > > > > >> Regards, > > > > >> Ritesh > > > > >> > > > > > > > > > > > > > > > -- > > > > > Pifta > > > > > > > > > > > > > > > > > -- > > Pifta > > >
