Code insights team
The code insights team is responsible for building and delivering code insights to engineering leaders, empowering data-driven decisions in engineering organizations.
- Joel Kwartler (Product Manager)
- Alicja Suska (Product Designer)
- Felix Becker (Engineering Manager)
To create a Sourcegraph code insights product that answers all your important high-level questions about what’s in your code and how it’s changing.
Sourcegraph users – especially those in leadership roles – create and monitor code insights to answer vital questions about their code, including:
- How their code is tracking against any migration, pattern, or code smell goals
- How their code is changing over time and what areas may need more or less developer attention
- Understanding their code’s current and historical content, like its languages, libraries, and structure
- What patterns or outliers exist in their third party tools’ data when viewed at a high level
- Any of the above questions, but also filtered by repository, engineering team, or other division
The code insights team is responsible for all code insights features, both backend and frontend.
While code insights is in prototype stage, the code insights team is also responsible for all support.
What is code insights?
Code insights is the first feature in Sourcegraph that can tell you things about your code at a high level.
Code insights dashboards will answer questions like “How is a migration progressing?”, “What areas of the code are most vulnerable to bugs?”, and “How many developers are using a specific API?” Code insights will also incorporate third-party data like code coverage or static analysis metrics to deliver on the promise of aggregating everything you can know about your code.
Sourcegraph is in the unique position to give these insights because we have universal code search: to know anything about your code at a high level confidently means you must know everything about your code at a low level.
Code insights connects many features that Sourcegraph already has and builds on top of them. We go beyond single-step code intelligence and search to connect the full cycle of analyzing (code intelligence), monitoring (code insights), and actionably changing a codebase (batch changes).
Code insights is the first feature primarily built for non-search-based user personas (developers), instead focusing first on the needs of engineering directors and VPs.
For more information about code insights, see the original product document or this demo of a code insights prototype. Anyone on the Sourcegraph team can create your own insight using the quickstart guide, which is explicitly not in the Sourcegraph docs because code insights is undergoing rapid development and this setup will soon change.
Goals and roadmap
Useful browser bookmarks ⭐️
The following bookmarks are useful to add to your browser’s bookmark bar if you’re on the code insights team. You can drag & drop these directly into your bookmarks bar.
- GitHub Project Board (fullscreen)
- New code insights issue (pre-fills labels and project)
- Use Developer Insights PR template (bookmarklet, run on the open-PR GitHub page to add our checklist template)
- Code Insights GDrive folder (all our documents are here or linked from here)
- Code Insights Roadmap
The team holds weekly syncs.
The meeting notes of team syncs can be found in this doc.
Before team syncs, teammates and stakeholders should write down under “Agenda” in the meeting notes document anything that they’d like to bring up for discussion with the whole team. Attendees are encouraged to add comments on talking points asynchronously before the meeting too.
Planning and prioritization
We plan and track our day-to-day work on our Kanban board. Our current process is as follows:
- Incoming tickets (e.g. from other teams) arrive in the Inbox column.
- Work is scheduled by adding a card to the Planned column. This happens after talking through the next priorities in our weekly sync or raising something asynchronously in the #code-insights Slack channel.
- The Planned column is an ordered column, by priority. Priority is discussed on the team.
- Work should not be moved into the Planned column until it is ready for development and estimated and prioritized.
- Work that is ready for development but not yet estimated or prioritized sits in the Ready for Dev column.
- Anything that needs design input gets the
needs-designlabel and goes in the Needs design column.
- When starting work, engineers pull cards from the Planned column and move it to the In Progress column.
- There should never be more than a couple of cards in the In Progress column at the same time. If we paused work on something (e.g. because priorities changed), it should be moved back to Planned or Icebox as appropriate.
- Things we triaged from the Inbox, but don’t plan to work on, go into the Icebox.
Note: we intentionally plan so we can avoid merging significant work less than two days before a release (if a release is on the 20th, our last day to merge is the 18th). Exceptions require explicit approval of both the PM and EM.
The team makes use of tracking issues for tracking progress on the implementation of longer projects that need to be broken up into multiple issues. The teammates should ensure that a tracking issue is created when starting work on features that are expected to take longer than a few days (or require multiple PRs) to deliver.
Specific product feedback about well-defined, small features can be found directly in the GitHub board. More general product feedback that applies to larger features, or that needs more research and planning to be actionable, is kept in Productboard.
Every two weeks, we hold a review/retrospective meeting to reflect on the past two weeks. We use this meeting to:
- Review the previous retro’s action items to ensure they get completed
- Give Shoutouts! to teammates to show appreciation for something they did that we appreciated
- Discuss things that went well in the past two weeks and that we should do more of / invest more into it
- Discuss the things that could have gone better and what we can learn from it to improve
- Talk about processes that we should revisit/refine/propose to improve our efficiency.
We capture and assign actions to individual teammates. Teammates should consider actions coming out of the retrospective as a very high priority.
Teammates contribute to the retrospective asynchronously during the iteration by adding their thoughts to our retrospective document. Teammates are highly encouraged to comment on points raised before the sync meeting in the document.
We rotate who leads the retrospective to allow all teammates an opportunity to lead the session. Teammates can find the rotation schedule at the top of the retrospective document.
The team follows the default code review guidelines with the following addition:
- If the author would like any of the requested reviewers to merge the PR after approval they add the label
- If the author would like their PR to be merged once all of the requested reviewers have approved it they add the label
- When there are only minor issues, reviewers are encouraged to give “approval with comments” and trust their teammates to address the comments without requiring a follow-up review.
Code Insights frontend
The most interesting part of the code insights UI are the charts. We use SVG and D3 libraries (d3-scales, d3-axis, d3-format) for this.
- SVG intro specs MDN Simple and short description of most popular aspects of SVG.
- Frontend masters D3 workshop Shirley Wu A very interesting workshop from Shirley Wu about SVG and d3 itself. If you prefer reading materials instead this workshop has a detailed description and sandbox on ObservableHq.com.
- React and pure d3 Amelia Wattenberger blog The interesting blog post about how to get on react as a rendering library and d3 as a tool for chart math.
- Sara Soueidan’s blog If you want to dive a little more into the peculiarities of SVG spec.
NOTE: The order is not important, you can read these as you like depending on what you are interested in.
Code Insights history
In mid-2020, Code Insights was born out of RFC 144: Code Insights, with the stated goal of being a Sourcegraph feature directly valuable to users in engineering leadership, in addition to individual developers. It was prototyped solely on the frontend to validate strong customer interest.
In late 2020, after the initial validation, and using the frontend-only functional prototype, a product designer and newly-hired product manager developed a detailed validation of use cases, customer excitement, potential directions, and the existing spaces the product fit into. Those findings are in PD 18: Code Insights.
In early 2021, seeing continued validation and opportunity, Code Insights became its own team separate from the “web team” (now 2021’s Developer Insights org).
In mid-2021 we made the first engineering hires to grow Code Insights to a full engineering team and bring the product to market.