diff --git a/doc/dev/adr/1653383629-use-tech-radar.md b/doc/dev/adr/1653383629-use-tech-radar.md new file mode 100644 index 00000000000..b11430d837d --- /dev/null +++ b/doc/dev/adr/1653383629-use-tech-radar.md @@ -0,0 +1,18 @@ +# 3. Use Tech Radar + +Date: 2022-05-24 + +### Context + +We want a quick visual overview of our tech stack: what's the established norms are, what has been explored, what has been rejected, and so on. We think this will improve developer onboarding as it will be easy to digest our stack for the new hires quickly. + +Proposed & discussed on May 12 during the [Backend Crew meeting](https://docs.google.com/document/d/1Y51d863Nuqr9BzbTbwwSF9jes0ro71vB724oc2p8qsQ/edit#heading=h.1cbmcls3l8u). Tech Radar is not unique for the back-end, and our ambition is to include both front-end and back-end tools, practices, libraries, etc. + +### Decision + +Build Sourcegraph Tech Radar. The initial version uses the [Build your Own Radar](https://www.thoughtworks.com/radar/byor) version hosted at Thoughtworks.com + +### Consequences + +- Improve understanding of our current tech stack. +- Improve onboarding. diff --git a/doc/dev/adr/index.md b/doc/dev/adr/index.md index 7f8390fc3f5..7cb3630a298 100644 --- a/doc/dev/adr/index.md +++ b/doc/dev/adr/index.md @@ -10,3 +10,4 @@ To preserve order, individual documents are prefixed by the **current epoch Unix 1. _2022-04-26_ [Record architecture decisions](1650968652-record-architecture-decisions.md) 2. _2022-05-13_ [Use Go for scripting purposes](1652433602-use-go-for-scripting.md) +3. _2022-05-24_ [Use Tech Radar](1653383629-use-tech-radar.md) diff --git a/doc/dev/how-to/index.md b/doc/dev/how-to/index.md index 6bde445cc10..48cd5684b2b 100644 --- a/doc/dev/how-to/index.md +++ b/doc/dev/how-to/index.md @@ -3,6 +3,7 @@ ## Documentation - [How to write great docs](https://documentation.divio.com/) (watch the video) +- [How to maintain the Tech Radar](maintain-tech-radar.md) ## New features diff --git a/doc/dev/how-to/maintain-tech-radar.md b/doc/dev/how-to/maintain-tech-radar.md new file mode 100644 index 00000000000..f790a3d8cdd --- /dev/null +++ b/doc/dev/how-to/maintain-tech-radar.md @@ -0,0 +1,14 @@ +### Running the tech radar + +- The radar is hosted at Thoughtworks.com, we only provide input data +- The input data is in the [tech-radar.csv](https://github.com/sourcegraph/sourcegraph/blob/main/doc/dev/radar/tech-radar.csv) file + +### Adding/removing entries + +- Modify [tech-radar.csv](https://github.com/sourcegraph/sourcegraph/blob/main/doc/dev/radar/tech-radar.csv) +- Preview the changes by linking your local version of the CSV file using the following address: https://radar.thoughtworks.com/?sheetId=https%3A%2F%2Fraw.githubusercontent.com%2Fsourcegraph%2Fsourcegraph%2{branch}%2Fdoc%2Fdev%2Fradar%2Ftech-radar.csv and replace {branch} wit your branch name + - For branch "my-radar" the URL is https://radar.thoughtworks.com/?sheetId=https%3A%2F%2Fraw.githubusercontent.com%2Fsourcegraph%2Fsourcegraph%2Fmy-radar%2Fdoc%2Fdev%2Fradar%2Ftech-radar.csv +- Once you merge your branch to the main the latest radar will reflect the changes you've made + +We're likely to simplify this process in the future by using `sg`. + diff --git a/doc/dev/index.md b/doc/dev/index.md index a489665f9ce..9be2014fef1 100644 --- a/doc/dev/index.md +++ b/doc/dev/index.md @@ -67,6 +67,7 @@ Clarification and discussion about key concepts, architecture, and development s ### Overview - [Tech stack](background-information/tech_stack.md) +- [Current Sourcegraph tech radar](https://radar.thoughtworks.com/?sheetId=https%3A%2F%2Fraw.githubusercontent.com%2Fsourcegraph%2Fsourcegraph%2Fmain2Fdoc%2Fdev%2Fradar%2Ftech-radar.csv) (also see [how to maintain the radar](how-to/maintain-tech-radar.md)) ### [Architecture](background-information/architecture/index.md) diff --git a/doc/dev/radar/tech-radar.csv b/doc/dev/radar/tech-radar.csv new file mode 100644 index 00000000000..68cbd5a8627 --- /dev/null +++ b/doc/dev/radar/tech-radar.csv @@ -0,0 +1,56 @@ +"name","ring","quadrant","isNew","description" +Go,Adopt,Languages,TRUE, +GRPC ,Trial,Backend,TRUE, +Datadog,Trial,Tooling,TRUE, +Buf,Assess,Backend,TRUE,"

We expect this will help us remove cumbersome, manual Protobuf setup

" +Mocha,Hold,Frontend,TRUE, +Jest,Adopt,Frontend,TRUE, +Typescript,Adopt,Languages,TRUE, +React,Adopt,Frontend,TRUE, +Buildkite ,Adopt,Tooling,TRUE, +GitHub Actions,Adopt,Tooling,TRUE, +log15,Hold,Backend,TRUE,

Unmaintained, poor semantics, lackluster performance, limited extensibility

+cockroachdb/errors,Adopt,Backend,TRUE,

Used internally by the lib/errors package

+Preprod Application tests,Trial,Tooling,TRUE, +Buildkite: stateless agents,Adopt,Tooling,TRUE, +Rust,Assess,Languages,TRUE,"kinda, it was already there in syntax-highlighter" +tree-sitter,Adopt,Backend,TRUE, +Elm,Trial,Languages,TRUE,"compute notebooks, codestat.dev, doctree" +Next.js,Adopt,Frontend,TRUE, +Tailwind CSS,Adopt,Frontend,TRUE, +Ruttl,Hold,Frontend,TRUE, +Markup,Trial,Frontend,TRUE, +Contentful CMS,Hold,Frontend,TRUE, +Strapi CMS,Adopt,Frontend,TRUE, +Netlify,Adopt,Frontend,TRUE, +Svelte,Hold,Frontend,TRUE, +SvelteKit,Hold,Frontend,TRUE, +CSS modules,Adopt,Frontend,TRUE, +Apollo Client,Adopt,Frontend,TRUE, +Monaco,Adopt,Frontend,TRUE,"used for search query and settings editor, want to get rid of it in favor of CodeMirror" +CodeMirror,Trial,Frontend,TRUE,"used for search query and Notebooks Markdown editor, under an experimental feature flag" +@testing-library/react,Adopt,Frontend,TRUE, +esbuild,Trial,Frontend,TRUE, +Playwright,Trial,Frontend,TRUE, +Sentry,Hold,Tooling,TRUE, +Bootstrap,Hold,Frontend,TRUE, +Enzyme,Hold,Frontend,TRUE, +Honeycomb,Adopt,Tooling,TRUE, +Elastic,Adopt,Tooling,TRUE, +Trivy,Adopt,Tooling,TRUE, +HackerOne,Adopt,Tooling,FALSE, +Executors,Adopt,Backend,TRUE, +stretchr/testify,Trial,Backend,TRUE,"mostly using for better assertions at this point" +Java,Adopt,Languages,TRUE,"JetBrains extension" +Gradle,Adopt,Tooling,TRUE,"JetBrains extension" +RxJS,Adopt,Frontend,TRUE, +Yarn,Adopt,Frontend,TRUE, +Storybook,Adopt,Tooling,TRUE, +ESLint,Adopt,Frontend,TRUE, +Prettier,Adopt,Frontend,TRUE, +Buildkite Analytics,Trial,Tooling,TRUE, +sourcegraph/run,Trial,Backend,TRUE, +sourcegraph/lib/log,Adopt,Backend,TRUE, Standardized logging package +sourcegraph/lib/errors,Adopt,Backend,TRUE, Standardized error package +sourcegraph/internal/observation,Adopt,Backend,TRUE, All-in-one operation observability package +sourcegraph/monitoring,Adopt,Backend,TRUE, Monitoring (alerts and dashboards) generation