Symbol documentation and Jump to definition in blob view (proof of concept)

Problem to solve

When reading code, the behavior or purpose of a function may not be clear, particularly if it is unfamiliar code. Using a local IDE this is often easy, with features like jump to definition and hovering for symbol documentation. Because of this it is easier to checkout code locally to understand it in detail.

Intended users

• Sasha (Software Developer)

Further details

Proposal

Mockup: blob view

⚠ This is a proof of concept, and should be feature flagged off by default. This will allow us to implement a first iteration that will not scale but will allow user testing.

Provide an experimental API to upload an LSIF dump:

• the API should expect that the LSIF dump is in sqlite format, not json (lsif-sqlite script can be used to convert before uploading)

If an LSIF dump has been uploaded for the current commit of the blob being viewed:

• hovering a symbol should show:
  • documentation
  • jump to definition link to the location (file and line) of the definition

Rather than importing the LSIF dump into the main GitLab database, which has scaling concerns and needs further investigation, the proof of concept should:

• read the LSIF data directly from object storage
• transform the LSIF file into a suitable response
• return the hoverable ranges, and all information needed to render it

Permissions and Security

• Only users with permission to view the repository should be permitted to request this information from the server

Documentation

Testing

What does success look like, and how can we measure that?

Solution validation:

• using the proof of concept we will conduct qualitative research (user testing) to further validate our proposed solution, and direction

Technical validation:

• the proof of concept will help us better understand the data structures and scaling considerations of offering this kind of feature for all projects on GitLab.com

What is the type of buyer?

The proof of concept will be disabled by default and available in Core while we conduct further investigation.

This feature is important to individual developers, browsing and reviewing code, however, the benefits of more powerful and better code review is most demanded by teams of engineers who review each others work.

Given this, we are still evaluating which tier this feature will be available in, and further solution validation and user feedback will be helpful in determining this.

Links / references