search

WorldBrain / WorldBrain-Engineering

This repository hosts the website documenting all our engineering pratices.
3 stars 2 forks source link

Document communication procedures around task preparation and implementation #2

Open ShishKabab opened 4 years ago

ShishKabab commented 4 years ago

We're using several tools to communicate from ideation of a task to the final implementation: Slack/Zoom, Notion and GitHub. Let's make this more explicit, so we can more easily discover ways to streamline the process and communicate it to contributors/followers.

One thing to still flesh out is the technical preparation of a task starts in a GitHub issue, and then when providing feedback on the implementation, the communication moves to a PR. Where to make this move from issue to PR is not always clear.

blackforestboi commented 4 years ago

In my head:

  1. Notion: High level feature requirements
  2. GitHub: Implementation progress reports and feedback (including summaries of outcomes of Zoom calls)
  3. Slack: emergencies?

Where to make this move from issue to PR is not always clear.

I feel that its kind of unnecessary to have a dedicated issue, except its a reported bug. Then the switch of comms to the PR could be at the point when the first commit is done.

ShishKabab commented 4 years ago

Notion: High level feature requirements

The line here may be a bit blurry here, like the performance investigation, which I could've also moved to a GH issue.

GitHub: Implementation progress reports and feedback (including summaries of outcomes of Zoom calls)

Great idea to make the knowledge generated during calls more explicit! I think this needs a bit more thought.

Slack: emergencies?

Introductions, pinging people for faster feedback on what's happening on GH (hey X, could you please review this), interactions on a human level, organizing events/calls, etc. Also, I think this has the unexpected positive side-effect that you can ping people on Slack for if you want somebody's attention ASAP, while using GH to tag people, but with a lower priority, which is a very welcome bonus for attention management.

I feel that its kind of unnecessary to have a dedicated issue

The problem is that an issue should be used for basic planning. Creating a PR with no code is a PITA. The https://github.com/WorldBrain/Memex/issues/948 was really useful for coordination for example.

cdharris commented 4 years ago

One thing to still flesh out is the technical preparation of a task starts in a GitHub issue, and then when providing feedback on the implementation, the communication moves to a PR. Where to make this move from issue to PR is not always clear.

Good points. I wanted to add the reasons why I think it's good to keep planning and progress reports in an Issue instead of a PR 1) The Issue can be opened before starting coding, to plan and collect contributions 2) An Issue for a feature or refactoring effort may span multiple pull requests. 3) It seems the way in which Github functionality is biased towards.

I do feel for the desire to reduce duplication and ambiguity though - How about if we decided on a separation of feature discussion and technical discussion, with a bias towards keeping everything in one place (the Issue) ?

Technical Discussion - PR So the PR is really only for discussion about the code or architecture, technical solutions, or code critique.

Feature or Product Discussion - Issue The Issue is where we talk about what is left to do, what is done, how a feature should work or doesn't work yet, adding new tasks, reviewing outstanding bugs, etc. If something is ambiguous, for the sake of ease, we put it in the issue.

Does that sound like a workable separation to attempt or does it still sound like too much duplication?