15:05:42 <aguestuser> #startmeeting application team docs meeting (2022-02-03)
15:05:42 <MeetBot> Meeting started Thu Feb  3 15:05:42 2022 UTC.  The chair is aguestuser. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:05:42 <MeetBot> Useful Commands: #action #agreed #help #info #idea #link #topic.
15:05:48 <sysrqb> \o/
15:05:58 <richard> congrats :)
15:06:04 <aguestuser> wow. i speak bot now. ;)
15:06:12 <aguestuser> bumping the pad: https://pad.riseup.net/p/tor-tbb-documentation-process-meeting-keep
15:06:19 <sysrqb> aguestuser: this means you're facilitating :)
15:06:29 <aguestuser> cool! let's rock!
15:06:42 <sysrqb> "The chair is aguestuser."
15:06:51 <aguestuser> so: i think the outcome of this meeting is some rough working consensus on where to put multi-repo docs
15:07:26 <aguestuser> specifically: the docs i want to write on building the several repos that go into an android build (for both alpha and stable releases)
15:07:52 <aguestuser> correlary goal: some rough consensus on where multi-repo docs in general should go. and what sorts of practices we want around them.
15:07:59 <sysrqb> does that include individually building fenix/mozAC, outside of tor-browser-build?
15:08:21 <sysrqb> or are you comfortable about where those docs should go?
15:08:50 <aguestuser> the itch i wanted to scratch here was specific to processes that spawn from running tbb-build for releases
15:09:08 <aguestuser> basically: i got a lot of advice from sysrqb and boklm in the form of bulleted lists
15:09:19 <aguestuser> and i would like those bulleted lists to live at a url or filepath somewhere
15:09:23 <richard> yes
15:09:23 <aguestuser> shared by the team
15:09:30 <aguestuser> (isntead of just in my emacs)
15:09:40 <richard> i similarly have a giant notes document
15:09:47 <aguestuser> so: scope is tbb-build flows that touch many repos -- where should they go?
15:09:47 <richard> with a lot of useful information
15:09:53 <sysrqb> we do like bulleted lists
15:10:00 <richard> mmhm, they are pretty great
15:10:07 <aguestuser> richard: what are some examples of stuff you have notes on?
15:10:20 <aguestuser> (i mean -- that seems tbb-build related)
15:10:29 <aguestuser> (i'm sure you have lots of great notes on lots of things!!! :))
15:10:36 <richard> the entire release process more or less (from tor-browser desktop side of things)
15:10:58 <richard> rebasing process, all the little errata that you run into
15:11:01 <aguestuser> cool -- so we would maybe like a place for release process for tbb-build (desktop and android) to live somewhere nice
15:11:02 <richard> and forget you need to rememebr
15:11:06 <richard> so they live in my docs *somewhere*
15:11:14 <sysrqb> the previous official documentation was: https://gitlab.torproject.org/tpo/applications/tor-browser-spec/-/blob/master/processes/ReleaseProcess
15:11:19 <aguestuser> (richard --- yes!!! i am quickly accumlating such a thing!!!)
15:11:26 <richard> yeah, but i think that this is a somewhat larger problem
15:11:36 <sysrqb> but that was hand-wavy w.r.t. the actual tor-browser-build changes
15:11:46 <richard> having been here for awhile
15:12:19 <richard> so the release-related notes, definitely need to be recorded (and maintanied!) somewhere so that we don't have keep passing on notes from lead to lead over time
15:12:27 <aguestuser> to help frame from where we jumped off in weekly meeting
15:12:33 <aguestuser> we had some options we were debating between
15:12:41 <aguestuser> (1) tor-browser-spec repo
15:12:54 <aguestuser> (2) tor-browser-build docs dir
15:13:01 <aguestuser> (3) wiki page *somewhere*
15:13:14 <richard> yes
15:13:21 <aguestuser> ((4) cool dev portal that doesn't exist yet, so de-scoped))
15:13:30 <PieroV> (gitlab wiki page)
15:13:33 <richard> so the wiki page *somewhere* situation we currently have, kind of sucks
15:13:44 <boklm> I think tor-browser-build is the central thing that is linking all the different repos together for a release, so I think it would be fine to have the docs about release in tor-browser-build/doc
15:14:01 <sysrqb> +1
15:14:04 <richard> +1
15:14:30 <PieroV> I kinda like (4)
15:14:42 <aguestuser> facilitator hat off: as a learner, tb-build is the natural repo my instincts lead me to look for this stuff
15:14:47 <aguestuser> facilitator hat on..
15:15:05 <aguestuser> in theory we could move whatever we do now to (4) later.
15:15:13 <PieroV> true
15:15:14 <aguestuser> does that satisfy PieroV's liking?
15:15:39 <PieroV> yep
15:15:42 <aguestuser> assuming we agree we like tbb-build as the *repo* we want this stuff to live in....
15:16:05 <aguestuser> does anyone have thoughts on whether it should be part of that repo's wiki or under version control?
15:16:30 <sysrqb> they are both under version control
15:16:42 <aguestuser> sorry: docs requires MR
15:16:43 <sysrqb> so using the wiki is less problematic
15:16:56 <sysrqb> true
15:17:05 <richard> the annoying thing about the wiki though, is that it isn't searchable
15:17:11 <sysrqb> "where would a sane person look for these docs?"
15:17:12 <richard> or else i've failed to find the search box for it
15:17:24 <richard> and taht is also a good point
15:17:29 <aguestuser> so one way to look at trade-off would be (1) wiki less heavyweight/noisy to update, less likely to get stale, (2) docs dir more discoverable, more likely to get stae ?
15:17:36 <boklm> if MR is a problem, we could say that small doc changes don't require a MR
15:17:37 <richard> do we only care about ourselves or do we also want to cater for sane people?
15:17:40 <PieroV> I think the generic GitLab search works also for wikis... if it works :)
15:17:59 <aguestuser> richard can you say more about why the wiki is not easy to search?
15:18:22 <aguestuser> sysrqb if it's true that it's under version control, could we sync wiki contents locally and use find/grep as our search?
15:18:28 <aguestuser> (as we would with 'docs' dir?)
15:18:35 <sysrqb> aguestuser: yes
15:18:49 <richard> hmm i guess it does actually search the wikis nevermind then
15:19:10 <aguestuser> boklm you seem to rather like the docs dir (and have put stuff there)... any objections to wiki approach? things we might not be thinking of?
15:19:36 <sysrqb> e.g., gitlab.torproject.org:tpo/applications/tor-browser.wiki.git
15:20:04 <sysrqb> richard: i've had trouble searching for content in the wiki before
15:20:14 <boklm> I like not having to open a web browser to read the doc, but maybe I can still do that with the wiki
15:20:28 <sysrqb> so, as with all search engines, "searching" is easy, but finding is sometimes hard
15:20:40 <richard> ooh wow, there's sneaky 'Clone repository' link for the wiki in the top right
15:20:47 <sysrqb> yep
15:21:07 <sysrqb> and you can build it locally :) but I haven't tried
15:21:11 <aguestuser> boklm (facilitator hat off): i also really like not having to use the browser to search! curious if cloned solution will help!
15:21:19 <richard> does it just give you a directory of markdown files or something?
15:21:28 <aguestuser> richard in my experience yes
15:21:37 <sysrqb> richard: yes, roughtly, iirc
15:21:43 <sysrqb> *roughly
15:21:49 <richard> OK
15:21:50 <sysrqb> wwith some structure and metadata
15:21:53 <aguestuser> i've tried one time previously to use locally-cloned wikis as repos. one stumbling block:
15:22:07 <aguestuser> i was not as primed to think of them as "something i need to sync"
15:22:27 <aguestuser> (b/c i didn't think of them as source code, and the main way i thought about editing them was in a browswer, which i was not in when in my text editor)
15:22:59 <sysrqb> emacs isn't a web browser? :)
15:23:08 <sysrqb> </sarcasm>
15:23:17 <aguestuser> lololol
15:23:51 <aguestuser> i mean -- tryig to keep an open mind to folks using lesser tools. ;) <-- sarcasm!
15:23:56 <richard> hmm
15:23:57 <sysrqb> but that's a good point
15:24:01 <aguestuser> ricahrd say more!
15:24:23 <richard> ok, so our docs have multiple audiences
15:24:29 <richard> there's docs that *we* need to do our jobs
15:24:48 <richard> in which case plonking them down in the tor-browser-build repo works great for my workflow (and I assume others)
15:25:10 <aguestuser> +1
15:25:13 <aguestuser> but...
15:25:21 <richard> but then there are also docs that other people in the org need for boring management and planning stuffs (like the Release Schedule for instance)
15:25:39 <richard> and docs that we want to point external partners to (Tor Browser spec for instance)
15:26:19 <sysrqb> (and docs that external projects/orgs use, like, say, projects forking tor-browser-build)
15:26:46 <aguestuser> any more?
15:26:54 <richard> and theoretically we also want to make the dev related docs discoverable to potential contributors
15:27:26 <richard> so I guess, ther's more here than 'where do we put the docs' because there is also the ongoing problem of docs becoming stale
15:27:34 <aguestuser> i *think* for now we were trying to scope to just tbb-build releated docs as a good example of how to learn how to better do other dev-flow related docs. is that fair?
15:27:44 <richard> it's much easier to ping boklm about some build problem, get the fix and move on with life
15:27:46 <aguestuser> (as a simplifying assumption for this discussion?)
15:28:12 <richard> when in reality we should probably be making an effort to write things down as part of our workflow
15:28:24 <aguestuser> (facilitator hat off): +100000000
15:28:58 <aguestuser> i can say that i think onboarding would have required a lot less brain cycles from sysrqb and bolkm if we had more of this stuff written down.
15:29:06 <aguestuser> (not that there was necessarily time to do that before)
15:29:12 <richard> yeah
15:29:20 <aguestuser> but now that we have more capacity, if we capture more processes in writing, we can move more smoothly
15:29:35 <richard> but i think/hope that this year with less things on fire and more capacity, we should make an effort to improve our quality of lives a bit here
15:29:36 <aguestuser> even just PieroV and i having "common knowledge" of what our shared build flow is for TBA
15:29:40 <sysrqb> yeah, prioritizing documentation is often difficult
15:29:41 <aguestuser> will be very smooth-i-fying
15:29:47 <richard> mmhm
15:30:10 <aguestuser> like aguestuser says "i'm on step X here at link <url>"
15:30:12 <sysrqb> that all sounds good
15:30:35 <aguestuser> back to last point --
15:30:44 <aguestuser> we were considering wiki vs. docs question
15:30:49 <aguestuser> and seemed to be nearing consensus
15:30:57 <richard> ah ok right sorry
15:31:05 <aguestuser> on a local-wiki-that-we-treat-like-source-code idea
15:31:09 <boklm> I think both the wiki and the docs dir are fine for me, with a small preference for the docs dir since it's more simple with a single repo
15:31:33 <aguestuser> boklm would you be open to an experiment where we tried out the wiki for a period of time and then evaluated?
15:31:59 <aguestuser> specifically: we could evaluate whether it is in fact true that it is (1) easier to update quickly (b/c not tied up in MR flows for shipping)
15:32:00 <sysrqb> i wonder if a helpful compromise is writing new docs under /docs in markdown?
15:32:09 <sysrqb> it won't provide the "quick" aspect of the wiki
15:32:13 <aguestuser> and (2) is it still discoverable publically via browser (b/c we sync it)
15:32:16 <richard> crazy thought: what if we made a docs folder as a submodule of each of our projects that points to the gitlab wiki?
15:32:18 <sysrqb> but it will be more readable in the web browser
15:32:34 <boklm> I think having the /docs in markdown is a good idea
15:32:57 <aguestuser> okay, i have a case study...
15:32:57 <richard> +1
15:33:13 <aguestuser> (and i am going to be out of facilitator mode here so... someone else maybe have an eye toward that)
15:33:14 <aguestuser> i am new!
15:33:15 <PieroV> richard: I think the submodule thing is very crazy
15:33:30 <aguestuser> i am noticing lots of stuff in "how to update gradle depencencies" that is stale
15:33:42 <aguestuser> in clasicall "joining an open source project" style...
15:33:48 <aguestuser> i learned how to do it by asking people
15:33:50 <aguestuser> figured it out
15:33:54 <aguestuser> and now i want to write it down
15:33:59 <aguestuser> i have a whole bunch of edits to that file
15:34:01 <aguestuser> (in docs)
15:34:09 <aguestuser> but i ahve git staged tehm and excluded them from my most recent MR
15:34:17 <aguestuser> because they are orthogonal to the build i want to get out
15:34:24 <aguestuser> and now they are chilling on my machine
15:34:41 <aguestuser> while i try to navigate the cognitive overhead of when and how to make an MR for these doc updates
15:34:50 <aguestuser> in this way to docs become stale over time
15:34:58 <aguestuser> the best time to update them is when it is fresh in my head
15:35:07 <richard> mmhm
15:35:09 <aguestuser> but b/c of process skews, that doesn't feel natural to do right now
15:35:11 <aguestuser> iff...
15:35:20 <aguestuser> there was a wiki i coudl update seperately and quickly
15:35:28 <aguestuser> i could do it right now in bits and pieces as i get new knowledge
15:35:32 <aguestuser> and iteratively improve our doccs
15:35:37 <aguestuser> in small chunks
15:35:40 <aguestuser> that don't require MRs
15:35:48 <aguestuser> or cogatnive overhad about thinking when to make them
15:35:55 <aguestuser> </end rant>
15:36:08 <richard> yeah that makes sense to me
15:36:10 <aguestuser> (the obvious implication of my user story being -- wiki would have been ehlpful for me in this instance)
15:36:44 <aguestuser> facilitator hat back on
15:36:45 <sysrqb> what if you created a separate branch with the doc updates and maintained changes there?
15:36:58 <sysrqb> i suppose the load of contexting switching woutldn't be fun
15:37:08 <aguestuser> does anyone want to review thos MRs?
15:37:13 <aguestuser> do they require review?
15:37:30 <sysrqb> we usually review them
15:37:38 <sysrqb> but we could be more lenient with doc updates going forward
15:37:39 <aguestuser> but yes -- eager to hear ideas about how we could help this theoretical person we just heard from get over this friction
15:37:44 <aguestuser> doesn't ahve to be by using wiki!
15:37:51 <sysrqb> if they are truly docs-only changes
15:37:56 <sysrqb> boklm: what do you think?
15:38:06 <sysrqb> reducing review of docs-only changes?
15:38:07 <PieroV> Having a second read is useful to catch errors or to see if someone that did not write the text can understand it
15:38:34 <boklm> I think we could reduce reviews of docs changes
15:39:07 <sysrqb> PieroV: I agree, but we have situations where doc updates never get merged because we have never finish improving the MR
15:39:09 <aguestuser> bolkm ie: (1) still review them but not pay as much attention while doing so or (2) not review them at all sometimes (or as much)?
15:39:39 <richard> I think we could safely limit review of doc changes to 'only request review if the author wants to make sure the additions are correct'
15:39:48 <aguestuser> PieroV curious -- as you have also been new: do you have any anecdotal evidence about stuff you've noticed while learning that you want documented and what's gotten in the way? or made it easier?
15:39:56 <richard> but I think as policy it becomes trickier when the docs live in the code repo itself
15:39:56 <sysrqb> PieroV: based on experience, the team could edit the docs more frequently and continue improving them
15:40:45 <PieroV> sure
15:41:04 <PieroV> the first one that comes to my mind was the enable-tor-launcher thing
15:41:19 <richard> +1++1
15:41:32 <sysrqb> that was always your favorite :)
15:41:44 <PieroV> a pro for wikis or any web-based content is that you can put screenshots for issues like this one
15:41:54 <richard> (it's 'fixed' in the esr91.6 branch assuming you know where to put tor-launcher)
15:42:31 <richard> that is very true
15:42:42 <aguestuser> sysrqb richard do you think need for review/quality control could be accmplished by somehow "mentioning" other devs on risky-seeming updates? (ie: the more knowledgable person would notice the change and could amend it later, but not block it from being changed beforehand)
15:43:20 <aguestuser> ^-- assuming a wiki/no-review model
15:43:42 <aguestuser> ^-- more knowledgeable person could also request it be amended
15:43:49 <richard> hmm
15:43:50 <boklm> I think we should try to merge docs MR fast, even if they are not perfect, or maybe even without requiring MR for small changes
15:44:24 <boklm> I think the good thing with the docs directory is that we get an email on the commits mailing list for those changes
15:44:37 <aguestuser> ooh. good point!
15:44:52 <richard> this may be a bit out in the weeds
15:44:55 <richard> but
15:45:00 <sysrqb> (email for any tor-browser-build commit, including docs)
15:45:08 <aguestuser> bolkm sysrqb is email notification possible if we have cloned the wiki "repo" for the repo?
15:45:35 <aguestuser> richard sorry, go...
15:45:35 <sysrqb> aguestuser: possibly, but it'll require investigation
15:45:35 <richard> ok the problem I see about not requiring review for /docs updates: how to we ensure someone doesn't try to sneak in code changes with doc updates
15:46:18 <gaba> Is not easier to have all this in the gitlab team wiki until we have the developer portal? (sorry i just skimmed backlog)
15:46:26 <aguestuser> hmm right. and ideally docs (in other rpojects anyway) are something that someone we don't trust that much could update
15:46:28 <PieroV> we considered -spec, but we could create a new repo that is called -doc
15:46:42 <PieroV> and put everything there... It would be obvious to look there
15:46:51 <sysrqb> richard: yeah, that's why i proposed "reduced review", and only you and boklm (and maybe gk and me) continue having merge powers
15:46:55 <richard> yeah basically that issue is what makes me uncomfortable with in-repo docs AND free-for-all doc editing
15:47:09 <sysrqb> richard: and all other MRs at least needs a high-level review that they're docs-only
15:47:15 <aguestuser> (gaba -- we are sort of inching toward gitlab wiki, but considering concerns against it)
15:48:08 <aguestuser> richard sysqrb one nice property of using the wiki is that presumably anyone could be given permissions to change it. less cognative load
15:48:29 <boklm> I think gitlab requires developer permission for editing the wiki
15:48:36 <sysrqb> but more cognative load in keeping them up-to-date
15:48:47 <sysrqb> yeah
15:48:53 <gaba> yes boklm. that is other problem we have
15:49:04 <sysrqb> aguestuser: we have already have documentation on the wiki(s)
15:49:04 <gaba> permissions on the repo. That is why we created a team wiki on each group in gitlab
15:49:07 <sysrqb> and we never update them
15:49:27 <sysrqb> i like the idea of bundling docs and code
15:49:38 <sysrqb> even if that requires a little more review of proposed changes
15:50:02 <sysrqb> but, this is not my responsbility anymore, so i'll stop voicing my opinion :)
15:50:11 <aguestuser> okay so, to step back, i think we have 2 alternative ideas (gimme a sec to frame them and we'll see if we have a strong pref):
15:50:12 <richard> lol
15:50:40 <aguestuser> (1) MRs for updates to /docs -- with some modifications to process for reviewing/approving them
15:51:28 <aguestuser> (2) updates to a tbb-build wiki -- that we try to make more dev-friendly by cloning locally and using version control / text editors
15:51:30 <boklm> I think being able to update some code and the corresponding doc in the same MR is nice
15:51:53 <aguestuser> and i'm hearing sysrqb and boklm leaning to (1)
15:52:19 <aguestuser> PieroV has brought up images as selling point for (2)
15:52:37 <aguestuser> i am worried that (1) is heavy therefore likely to become stale and (2) might be more nimble
15:52:45 <aguestuser> ricahrd leans...
15:52:46 <aguestuser> where?
15:52:57 <richard> I like a combo idea tbh
15:53:06 <aguestuser> neat! elaborate?
15:53:20 <richard> put the docs in a separate wiki repo, link it from /docs
15:53:22 <sysrqb> (meta: time check.)
15:53:31 <aguestuser> (for context: some of my concerns are addressed by quick-MR-review thing)
15:53:35 <aguestuser> sysrqb thx!
15:53:40 <aguestuser> richard yes..
15:53:43 <richard> nice web interface for screenshots f you like (which I do like)
15:53:50 <richard> but also right there at the command line grepable if you need it
15:53:54 <sysrqb> (i believe there may be another meeting in ~5 min)
15:54:19 <richard> (is it possible to make a wiki-only gitlab project?)
15:54:31 <richard> i think having *all* of hte docs in a single git repo also has some nice side benefits
15:54:38 <sysrqb> richard: that is roughly what "team" is
15:54:51 <richard> especially with how, interconnected all of our projects are
15:55:08 <aguestuser> so.
15:55:09 <aguestuser> (3)
15:55:27 <aguestuser> use the wiki of the teams page instead of tbb-build page
15:55:29 <gaba> yes, we have a team repo in each group in gitlab to have teh wiki
15:55:32 <aguestuser> (repo)
15:55:42 <aguestuser> and address concerns about being able to access quickly by...
15:55:49 <aguestuser> (a) linkking in /docs
15:56:01 <gaba> +1 (3) :) (2cents of a vote)
15:56:03 <aguestuser> (b) suggesting people clone locally, interact with it via git?
15:56:41 <richard> interact via git or the web interface as is appropriate
15:56:54 <aguestuser> sysrqb as proponents of "let docs live with code" and "want to review these things" -- does that approach leave room for stuff you want?
15:57:07 <richard> but it keeps the docs out of code MRs, making it no hadrer than linking torbuton/tor-launcher/tor-browser MRs
15:57:18 <aguestuser> perhaps as a 1-month experiment to be revisited to see if it works?
15:57:24 <aguestuser> also: VERY close on time
15:57:45 <aguestuser> sorta want to kick to richard to decide whether we're close enough to agreed-upon to have a decision or (hope not!) need to kick to another meeting
15:57:56 <sysrqb> aguestuser: i won't block either path
15:57:57 <richard> we can move convo over to #tor-dev after
15:58:09 <aguestuser> richard cool! my sense is we're close but have some not-quite resolved concerns from sysrqb boklm
15:58:10 <sysrqb> but i worry that long-term, separation will result in stale docs
15:58:18 <sysrqb> but that can be an experiment
15:58:22 <richard> ok before we go: one thing we need to do regardless
15:58:45 <richard> can we go to that pad and list out the topics that need official documentation?
15:59:15 <richard> (after this meeting ;) )
15:59:17 <sysrqb> we can start, but we should probably end this meeting, so we don't block the next one :)
15:59:18 <aguestuser> as todo items to check in on at weekly meeting
15:59:24 <aguestuser> yes! how do i do that?
15:59:25 <sysrqb> ah, yeah.
15:59:29 <sysrqb> #endmeeting
15:59:32 <aguestuser> #endmeeting