Skip to content
This repository has been archived by the owner on Sep 30, 2024. It is now read-only.

Improve engineering onboarding: tooling #31005

Closed
35 of 39 tasks
taylorsperry opened this issue Feb 10, 2022 · 7 comments
Closed
35 of 39 tasks

Improve engineering onboarding: tooling #31005

taylorsperry opened this issue Feb 10, 2022 · 7 comments
Assignees
@bobheadxi
Labels
roadmap Issue tracking a product-eng roadmap item tracking

Comments

@taylorsperry
Copy link
Contributor

taylorsperry commented Feb 10, 2022 •
edited by bobheadxi
Loading

Problem to solve

sg has become an integral part of engineering at Sourcegraph. There are several categories of issues that need to be resolved due to its rapid growth and adoption.

  • New Sourcegraph developers end up being guinea pigs for our sg setup tool because we don't have an automated testing process in place, and similarly for some other features of the sg
  • Features have been haphazardly implemented, and we may need to start implementing a better architecture internally to keep up with new features. This most noticeably applies to features that have multiple internal job/task types (sg lint, sg generate, sg test, etc.)
  • We may have outgrown the capabilities of the current CLI framework of choice, and would benefit from a more feature-rich framework that enables (for example) better feature discovery
  • We have no visibility into feature usage, adoption, and feedback for sg
  • Lots of rough edges could be improved: sg doctor, update experience, intro guide to sg, half-migrated tools - many tasks can (and are) still invoked both directly and via sg.

Issues with sg are becoming increasingly prominent and disruptive (e.g. many engineers fixing ) so it is important we tackle improvements to smooth out the experience and lay the groundwork for future investments.

Measure of success

  • sg features better suggestions, completions, and convenience features for improved CLI UX
  • sg has robust internal frameworks for implementing lints, tests, and generate tasks
  • sg has more robust features for getting started on "inner development loop":
    • Integration testing of core features
    • Checks and generate tasks are unified across CI and local dev
  • Reduced size of sg.config.yaml
  • Feedback and analytics on sg usage

Solution summary

New teammates should be set up for success on day one of the job so that they can start contributing productively as soon as possible.

Artifacts: none

What specific customers are we iterating on the problem and solution with?

Sourcegraph developers

Impact on use cases

Delivery plan

  • Identify roadmap of action items
  • Make sg approachable as it scales: completions, suggestions, unified documentation
  • Make development of tasks in sg easy to scale: framework migration, implementation of internal frameworks for testing, code generation, and scripting tasks
  • Migrate some shell scripts into Go-based implementations with sg: checks, code generation, misc. tooling
  • sg setup gets automated testing and also supports the use case of ensuring an environment stays up to date (automated fixes)
  • Unify linting tasks across CI and local dev using sg
  • sg exports metrics indicating usage, timing, and error trends, and metrics are viewable in OkayHQ

Tracked issues

@unassigned: 9.00d

Completed: 6.00d

@bobheadxi: 28.00d

Completed: 27.00d

@burmudar: 2.50d

Completed: 2.50d

@jhchabran: 1.00d

Completed: 1.00d

@marekweb: 1.00d

Completed: 1.00d

Legend

  • 👩 Customer issue
  • 🐛 Bug
  • 🧶 Technical debt
  • 🎩 Quality of life
  • 🛠️ Roadmap
  • 🕵️ Spike
  • 🔒 Security issue
  • 🙆 Stretch goal
@taylorsperry taylorsperry added roadmap Issue tracking a product-eng roadmap item planning team/devx sg-setup sg setup related tasks labels Feb 10, 2022
@taylorsperry taylorsperry self-assigned this Feb 10, 2022
@sourcegraph-bot sourcegraph-bot mentioned this issue Feb 10, 2022
Closed
16 tasks
@taylorsperry
Copy link
Contributor Author

@jhchabran Would you please help me flesh this out?

@bobheadxi bobheadxi changed the title Improve engineering onboarding: sg-setup Planning Issue Improve engineering onboarding: sg setup Feb 10, 2022
@bobheadxi bobheadxi changed the title Improve engineering onboarding: sg setup Improve engineering onboarding: tooling Feb 11, 2022
@jyavorska jyavorska removed the roadmap Issue tracking a product-eng roadmap item label Feb 16, 2022
@bobheadxi
Copy link
Member

Idea: expand to welcome-to-sourcegraph functionality improvements. We could target:

  • sg test
  • sg check/lint

^ unify across ci and local

@bobheadxi bobheadxi mentioned this issue Feb 23, 2022
Closed
@taylorsperry taylorsperry added the roadmap Issue tracking a product-eng roadmap item label Mar 9, 2022
@bobheadxi
Copy link
Member

Scratchpad for ideas: https://docs.google.com/document/d/1NS_C3te-59P149LD_rrL1zcflNqqZOoSHVJfv8oPcqY/edit

@bobheadxi bobheadxi mentioned this issue Mar 21, 2022
Merged
@bobheadxi bobheadxi added devx/onboarding-tooling tracking and removed sg-setup sg setup related tasks labels Mar 30, 2022
@jhchabran
Copy link
Contributor

jhchabran commented Apr 14, 2022 •
edited
Loading

Reduced size of sg.config.yaml

@bobheadxi Could you elaborate on why this is a measure of success? If this translates in more ad-hoc code for example on the Go side, I'm not sure that's an actual win, as most people are comfortable editing the config but not that much the code itself. So I'm curious about the motivations behind this reasoning, to make sure I'm not missing something 😊

@bobheadxi
Copy link
Member

bobheadxi commented Apr 14, 2022 •
edited
Loading

@bobheadxi Could you elaborate on why this is a measure of success? If this translates in more ad-hoc code for example on the Go side, I'm not sure that's an actual win, as most people are comfortable editing the config but not that much the code itself.

Ah, I forgot to open an issue about this - some other approaches are better utilities within the YAML, splitting it up by team/domain, etc, though it's quite open to interpretation

@jhchabran and even if folks are comfortable editing the config, I doubt that will stay that way for long as we reach over 1000 lines of YAML configuration (see "Problems to Solve") - it will soon (and IMO already has) become incredibly daunting to change. I think with something like https://github.com/sourcegraph/sourcegraph/issues/33871 we might even be better off having things be in code

=> https://github.com/sourcegraph/sourcegraph/issues/33913

@sourcegraph-bot sourcegraph-bot mentioned this issue Apr 28, 2022
Closed
14 tasks
@bobheadxi
Copy link
Member

bobheadxi commented Jun 23, 2022 •
edited
Loading

There are only two core items left here:

sg setup gets automated testing and also supports the use case of ensuring an environment stays up to date (automated fixes)

This is almost done - we just need to merge https://github.com/sourcegraph/sourcegraph/pull/37528, replace the old sg setup, and do the appropriate communication/guidance!

sg exports metrics indicating usage, timing, and error trends, and metrics are viewable in OkayHQ

We are exporting some data here, but I think we should revisit our OkayHQ investment. That said, the core of the work - frameworks for collecting data and exporting it - is already done, so switching to a new backend will be trivial (though we will lose some data unfortunately)

The remaining issues in the list are a long tail of improvements, and do not need to be part of this project.

@sourcegraph-bot sourcegraph-bot mentioned this issue Jun 28, 2022
Closed
12 tasks
@bobheadxi
Copy link
Member

I'm closing this now - with the sg setup cutover I think we are in a good spot, and we are revisiting analytics in the coming bet.

Closed
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@bobheadxi bobheadxi

Labels
roadmap Issue tracking a product-eng roadmap item tracking
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@jhchabran @jyavorska @bobheadxi @taylorsperry