Shipping more quickly

[kgodey]

Our current top priority is to get Mathesar in the hands of real users as soon as possible. In our weekly discussion this week, we talked about how our work has slowed down in the last few weeks. There were a lot of ideas about how we can increase our speed.

I'll put each idea in its own post to encourage targeted discussion. Others are welcome to add new ideas as well:

• Adopting a "Feature First" Approach
• Product & Design Review Teams
• Product & Design Creation Process
• Facilitating Synchronous Discussions
• Reducing Notifications
• Speeding up Code Review
• More Focused Issues
• Milestone Scope
• Behavior Driven Development

[kgodey]

Adopting a "Feature First" Approach

Many of us have been guilty of focusing on perfecting technical architecture over completing features quickly. Instead, our primary goal should be completing the feature as specced in the design, even if that involves something "hacky" or isn't great for future extensibility. We should also not be over-designing features to work more generally (e.g. aiming towards releasing a general component library or a general release of the db backend module), the work we do should support the UX we have planned and no more.

With this approach, we will accrue technical debt, but that's a trade off we're willing to make at this stage. To help mitigate this, it's always helpful to open a GitHub issue to track known issues and hacks when it's fresh on your mind.

Everyone should:

• be extremely vigilant about making sure you're prioritizing feature work over architecture on a day-to-day basis.
• speak up if you could use help with making sure you're focusing on the right things.

[dmos62]

Tracking technical debt in the issue tracker is a good idea. Currently we have one technical debt related label affects: technical debt. It seems to be meant to label solutions to technical debt. Might be helpful to introduce another label like type: technical debt for just tracking occurrences of tech debt.

[kgodey]

I'm not sure what the difference between a solution to technical debt and an occurrence of technical debt is.

[mathemancer]

A likely sacrifice of this approach will be the accessibility of the code base for outside contributors. (It will also bog us down over time, but I think that's already in the calculation mentioned above regarding tech debt.)

[dmos62]

I'm not sure what the difference between a solution to technical debt and an occurrence of technical debt is.

It's the difference between a problem and a solution. One might notice that there's a problem that we would want to address, but might not see the obvious correct solution to that problem. If that were the case, the hypothetical poster couldn't formulate the ticket as a solution.

[kgodey]

@dmos62 I think it's fine to have the "Proposed solution" section in the issue template say something like "Not sure, need to research and evaluate solutions." and set the status label of the ticket to status: draft.

I'm also fine with changing the affects: technical debt label to type: technical debt, but I don't think we should have two labels for technical debt since it will be confusing to figure out what to use when.

[kgodey]

Product & Design Review Teams

@seancolsen has suggested creating dedicated product and design review teams to review new product and design work. I think this is a good idea, it will reduce the number of people involved in the review process and make responsibility for who needs to review each spec very clear.

@ghislaineguerin and @kgodey will be on both teams. We should have at least one backend and one frontend engineer on both as well. We need volunteers for the product and design review teams, please post below.

Any other thoughts on this proposal are welcome here as well.

[pavish]

I'd like to be on both teams.

[silentninja]

I'd like to be on the Product Team

[mathemancer]

I'd like to be on both teams.

[dmos62]

I think these reviews will take some time, so I can be on the product team to share the workload.

[kgodey]

I've documented the Design Review team on the Design Review Guidelines page.

There is no wiki page describing the product review process yet, it's been pretty ad-hoc so far. Once we've finalized how the process works, I'll document the product review team in the relevant documentation.

[kgodey]

Product & Design Creation Process

No changes are planned here since I don't think it is affecting our speed, product and design is well ahead of implementation at the moment.

One of the things that came up is that visual design should be improvised during implementation. I don't think this is the case - visual design should follow the prototype as closely as possible and only be improvised if there's something missing in the prototype. @ghislaineguerin and I are putting a lot of thought into design patterns and that should be reflected in the actual UI.

[ghislaineguerin]

I agree on having a sync call to discuss this

[seancolsen]

I don't think it is affecting our speed

For me personally, product and design has been the #2 thing slowing me down. (Second to the over-prioritization of architecture perfection).

Why?

• The product and design process has been slowing my productivity because I've spent significant time participating in product and design review that I could have spent building front end features. I've recently decided to personally de-prioritize my involvement in product and design review, but I think it's worth considering our workflow as we onboard new team members so that they don't get sucked into participating in the product and design review more than they should. The new teams structure mentioned above will help a lot I think!
• (more minor note) The features I've worked on have often required significant improvisation during implementation, sometimes opening up new design questions. Most recently UI for adding multi-column unique constraints #1005, for example. Personally, I'd be able to move faster if the designs were more specific. I'm used to working with designs that specify the UI in near-pixel-perfect terms. However, creating more specific designs might not actually improve our overall team efficiency, as it would just be shifting some of the design work earlier in the process.

[seancolsen]

I agree on having a sync call to discuss this

I added it to the agenda

[kgodey]

@seancolsen By "product and design process" in this point, I mean only the spec and design creation process. The review process is addressed under Product and Design Teams above, hopefully that helps.

I agree it makes sense to discuss how much improvisation/design specificity is necessary at the next weekly meeting.

[seancolsen]

Thanks for the clarification. Yes I'm in agreement with you now, @kgodey

[kgodey]

Facilitating Synchronous Discussions

I've set up a weekly meeting for 6 weeks to hopefully improve our process around having synchronous discussions to resolve issues. People are encouraged to add agenda items to the meeting notes document any time during the week. We will cancel the meeting if there are no agenda items set in the HackMD meeting notes by the 5 PM US Eastern time on the previous day.

This is not meant to be a replacement for more targeted meetings, it's just to help us ease into the habit of talking to each other to resolve issues. We should still be proactively scheduling targeted meetings about specific issues if they will be helpful.

[kgodey]

Reducing Notifications

We discussed this during the State of Mathesar meeting so I won't go into more detail here. Just a couple of questions:

• How does everyone feel about the level of notifications that you're getting? Do you need help reducing them?
• Do people find the Code - Review channel useful or should we try to use GitHub notifications exclusively for review?

[pavish]

Our Code - Review channel is currently also used for other purposes. On the top of my head:

• Indicating urgency of certain PRs
• Asking optional reviews on draft PRs
• Informing everyone on specific changes, without needing their input
• Informing updates on our staging repo

Assigning people on GH for these cases have a larger round-trip time, which may not be desirable.

I personally don't find the notification level to be distracting.

Having said that, I think we can use the Code - frontend/backend channels for these scenarios, and eliminate Code - Review.

[dmos62]

How does everyone feel about the level of notifications that you're getting? Do you need help reducing them?

My notification information-to-noise ratio is good. However, it would be better if I didn't get automatically subscribed to issues I wasn't mentioned or requested in. I think it was mentioned that I can configure that; haven't taken the time yet (I guess it's not that bad yet.

Do people find the Code - Review channel useful or should we try to use GitHub notifications exclusively for review?

I do. I feel more assured that my review requests are being noticed without unnecessary delay. I can also easily track others' PRs' progress.

[seancolsen]

I've left the Code - Review channel. I imagine that should cover my concerns, as long as people are also tagging me in GH when needed.

[kgodey]

Having said that, I think we can use the Code - frontend/backend channels for these scenarios, and eliminate Code - Review.

We were doing this in the general code channel before we had a review channel but we decided to create a dedicated channel because review requests would often get drowned by longer conversations. I think we should keep the Code - Review channel and people who find the notifications distracting can leave or mute. As long as PRs are getting reviewed in a timely manner, how people choose to get notified is fine.

@seancolsen I assume you'll temporarily join the Code - Review channel in case you need to update others about the types of things @pavish mentioned.

[kgodey]

I updated the Code Review Guidelines wiki page to say that posting on the Code - Review channel is optional and can be used for urgent PRs or optional review of draft PRs.

[kgodey]

Speeding up Code Review

These points came out of some 1:1 calls I had with various people but I think it's worth mentioning here.

• We should be aiming to turn around PR reviews within 1-2 working days. This means that there should be movement on the PR every 1-2 days, a new review, code review fixes, repeat if needed, and then merge.
• We should be aiming to merge PRs in and create new issues for improvements rather than keeping PRs in review until every possible issue is fixed.
• Code review should be a fairly quick process. Reviewers should be focused on asking the right questions, not on doing research into the answers and suggesting them.
  • e.g. if you're wondering if the author considered a particular implication of a change they made, ask them that instead of doing research into all the implications yourself and informing the author of them.
• If you'd like to reconsider the architecture of a PR, create a draft issue for figuring that out rather than blocking the PR until you figure out the right architecture.
• When reviewing community contributed PRs, if it's easier to make the changes yourself rather than describe the changes needed as a code review, just make the changes and merge the PR. You can explain what you did and thank the contributor for their work.

[kgodey]

That's fine, this is meant to be a guideline that helps us make smaller PRs and not overthink code review. I don't think we need a separate rule of thumb for larger PRs.

[dmos62]

We could get creative in making PRs smaller. For example, splitting a large PR into smaller PRs that target a non-master branch. That way we can make PRs that break things or don't make sense on their own, provided that upcoming PRs will resolve that, and when ready merge that branch into master.

We did something similar for the current functions API PR, but instead of targeting a dedicated branch, we're targeting master, but structured changes in a way that doesn't affect existing APIs. The breaking changes will come in a subsequent PR.

[seancolsen]

@kgodey I found myself revisiting your above bullet points for a second time today, just to help steer me towards the best level of critique for the PR I'm currently reviewing. I like your guidelines a lot. After this discussion has settled, I think it would be good to codify those guidelines on the Code Review Guidelines wiki page, especially to help new team members later on.

[kgodey]

@seancolsen I'll do that, thanks.

[kgodey]

These guidelines are now in the Code Review Guidelines page.

[kgodey]

More Focused Issues

There was some feedback from @silentninja about creating more focused issues, both in terms of separation of concerns and level of detail in each issues. I do think having clear expected outcomes for each issue will help us keep PRs more focused. It will also help new contributors get into issues more easily, which is a nice side benefit.

I think the takeaway here is to put some extra time into creating detailed issues with clear expected outcomes, it will save us time in the implementation phase. @seancolsen has been doing a great job with the new issues for the NULL and foreign key specs, and they can serve as a model to emulate.

[kgodey]

Milestone Scope

Feedback from @silentninja:

Linear Milestone - Currently our milestones are linear, so this makes our work aim for perfection. We should rather aim to have an extended(or future) counterpart for the milestone. While we have it various forms as of now(future tags, future ideas wiki page), it would be much better if we have it as a milestone, as it would make us actually use it and think about it when working on day to day basis,

The scope for each milestone is decided during the design phase – we create the design based on requirements for the alpha release and then create GitHub issues to implement that design. I'm not sure that redoing the way we do milestones will have much effect as long as we're only focused on implementing what we spec.

Further thoughts welcome.

[seancolsen]

I think that the "More Focused Issues" intervention (above) will offer some help on avoiding the "aim for perfection" pitfall by allowing us to apply more granular prioritization to features. We can put the important bits in the nearby milestones. And put the less important bits later on down the roadmap.

[silentninja]

I don't mean to say we redo the milestone from design spec, rather the extended milestone is for issues that crop up when implementing the features.

Right now most of the future issues are something we are unsure of or good to have features, rather it should be comprised of features we don't need for alpha but will be coming in beta, by not having an extended milestone, we tend to give off the vibe that there won't be a further enhancement to this existing milestone. Having an extended/future milestone would make us think we don't have to do it immediately.

It could also benefit us in future as we wouldn't have to reorganise milestones again.

[kgodey]

@silentninja So far, we have not been speccing out features past the alpha release. Could you give me an example of an issue that would go in an extended milestone? Multiple examples would be better.

[kgodey]

Behavior Driven Development

Feedback from @silentninja:

Behaviour Driven Developement - Having BDD style test for UI apis and unittest for db and logic testing of UI apis would help us focus better on features rather than architecture, creating a good separation of concern.

I'm not sure if it's worth taking the time to introduce a new type of testing before the alpha release, especially since not everyone on the team is familiar with the tools involved. I think we should defer this until after the alpha release.

Further thoughts welcome.

[seancolsen]

@silentninja

BDD

Having never before used BDD or Gherkin, I'm interested to learn. I skimmed over the Gherkin page when you first suggested it to me (in think in a DM, if I recall), and my initial reaction was "thinking more deeply about this does not seem like a good use of my time right now".

BDD is more of a paradigm than tooling, we could do it without any tools if required.

Cool. If there are ways you could nudge us in the direction of BDD with suggestions that are quick and straightforward, I'd be keen to explore them.

Page Object Model

You also suggested Page Object Model to me, and I had the same reaction -- I'm trying to get this E2E stuff done as quick as possible so I can get back to building features. I did notice that Playwright has some features built around Page Object Model. In my web searching to troubleshoot issues with Playwright, I also noticed that a lot of people using Playwright seem to be also use Page Object Model. So I think it might be worth exploring more, once we're doing more E2E testing.

Next steps

My rough plan with the E2E testing is:

1. Get Improve E2E test setup #1032 ready to merge by satisfying all the goals mentioned in the PR description.
2. Make another PR which adds roughly 10 more E2E tests, providing more coverage.

After that, it might be a good time for you to open a PR which makes some changes to one or more of our E2E tests, adapting them to follow BDD (or even Page Object Model). With BDD being more of a paradigm (and thus more nebulous, conceptually), I think that it will be easier for other team members like me to critique your suggestions if we're looking at something concrete like a diff.

Terminology

would rather start with e2e tests and create integration tests required for the e2e test.

I also want to acknowledge that we seem to be using the terms "E2E" tests and "Integration" tests to refer to the same thing -- the highest level of testing -- whereas other teams might use these terms more distinctly, with "E2E" being the highest level and "integration" being slightly lower level (like our current API tests). I'm fine with this though. Testing terminology has always seemed somewhat blurry and subjective to me.

[silentninja]

Maintenance work is a necessary evil, From a developer's, perspective testing is mostly a time drain and might seem like not worth it, but it pays off in the long run. It might seem tempting to put architectural work and maintenance work for later, we might be accruing technical debt which we might have to pay off with interest.

Introducing certain things in future might mean that we would have to redo certain things and the larger its impact, the harder it will be to introduce a change, for example trying to introduce BDD to backend testing would be really hard at this point and I am not sure if it is even worth it. While I do acknowledge features are what the users will be using, we should also be mindful of our technical debt.

Like @seancolsen said, I could try making a draft PR for the E2E test cases and if does seem plausible, we could use it.

[kgodey]

@silentninja The issue with this suggestion is that I'm not sure what problem it solves – you've indicated that it will help us think about features more, but that seems like a high-level point. For most of the other points in this discussion (e.g. speeding up code review, creating more focused issues, creating the product and design review teams), I can come up with a specific recent issue or discussion that triggered the workflow change. Even the current E2E tests that @seancolsen is working on are being prioritized because it's slowing down frontend work to manually test that previous features are not broken while building a new feature.

Could you give us a concrete example of how you putting extra time into this (which also entails taking away time from our specced features) will help us increase speed in the short term?

[silentninja]

I think there is a miscommunication here

1. BDD is a way of writing test cases, it does not even need tooling or any extra time, this is just like code styling. Most of the test cases that test the service layer of the backend are similar to BDD, just that it is not explicitly stated

Given a table with data
When a filter is applied
Should return the filtered response

I am just trying to say that we if follow this method, we start implementation from how to make a feature work and then create the required architecture. This is also possible if we start writing test cases first, just that BDD would give us clarity as it is just plain English. This is to address the concern of how to make us think in terms of features first.

2. BDD tools - While not necessary, but can enforce the behaviour just a good linting tool. This also gives us the added benefit of having a human-readable test case that can serve as good documentation and easier to search test cases.

BDD would be a disaster we tend to implement features and then write test cases just for the sake of it.

@kgodey This issue is to adopt a Feature first approach

[kgodey]

@silentninja Thanks for the explanation. I'm still not sure what the action items for us would be, though. You mention that we should "follow this method" - what concrete changes are you proposing that we make to our process, workflow, and/or code?