sourcegraph / handbook Goto Github PK
View Code? Open in Web Editor NEWπ The Sourcegraph handbook
Home Page: https://handbook.sourcegraph.com
License: Apache License 2.0
π The Sourcegraph handbook
Home Page: https://handbook.sourcegraph.com
License: Apache License 2.0
We are getting rate-limited for our requests to the GitHub API, resulting in the contributors section not showing up often.
Possible solution: Use https://www.npmjs.com/package/netlify-plugin-cache-nextjs, which may result in NextJS simply not rebuilding unchanged pages and therefor also not triggering new API requests. I'm not sure on that though, seems worth trying our first, could be beneficial in general.
If that still results in pages to be rebuilt, we can:
git log $PATH --pretty=%H --max-count=1
locally to get the commit SHA of the last change to the fileWe should set up GitHub Action checks like in the about repo.
Add documentation about the benefits of the auto-merge feature in the handbook repo
I would love the ability to include a section of content from another page in the handbook. This would allow us to inline valuable pieces of information in multiple places in the handbook, while preserving a single source of truth in the source markdown.
Examples of pieces of information that are valuable scoped to a specific team/org, but also valuable to see as a department/company:
Can read from the git history and display GitHub avatars.
Design: https://www.figma.com/file/ze8C5qjzSTadKv2LYmON1T/Handbook-Wizardry?node-id=1144%3A3095
Swiftype has a related content module I'd like to try out. I've configured it here.
It's currently hard to find an error in the output of the dead link checker.
We can fix this by using the programmatic API from our own small JS script. This would also be necessary anyway for more improvements, like #82 and making sure all pages have inlinks.
The large file check currently rejects all large files that are over 100KB and binary (e.g. PNG, JPG, MP4).
However, sometimes plain text files include large binary content in a sneaky way that makes them equally/even larger than the equivalent binary file. E.g. an SVG that actually includes an <image>
with a Base64 data:
URI encoding a JPG, or even including an entire font (this actually existed in the handbook prior to the migration). The check currently doesn't catch these.
What it could do is in addition to binary files, match the content for long Base64 strings with a regex (e.g. \w{100,}
). If the file is larger than 100KB and not binary, but contains any such strings (or passes a length threshold of the sum of the strings), it should also be rejected.
I followed the instructions in the readme to run locally on a fresh checkout and got the following error:
nick@Nicks-MBP dev % git clone [email protected]:sourcegraph/handbook.git
Cloning into 'handbook'...
remote: Enumerating objects: 26624, done.
remote: Counting objects: 100% (1702/1702), done.
remote: Compressing objects: 100% (882/882), done.
remote: Total 26624 (delta 994), reused 1268 (delta 784), pack-reused 24922
Receiving objects: 100% (26624/26624), 7.81 MiB | 12.29 MiB/s, done.
Resolving deltas: 100% (15579/15579), done.
nick@Nicks-MBP dev % cd handbook
nick@Nicks-MBP handbook % yarn
yarn install v1.22.11
[1/4] π Resolving packages...
warning Resolution field "[email protected]" is incompatible with requested version "unist-util-visit-parents@^4.0.0"
warning Resolution field "[email protected]" is incompatible with requested version "unist-util-is@^4.0.0"
warning Resolution field "[email protected]" is incompatible with requested version "unist-util-visit-parents@^3.0.0"
warning Resolution field "[email protected]" is incompatible with requested version "unist-util-visit-parents@^4.0.0"
warning Resolution field "[email protected]" is incompatible with requested version "unist-util-is@^4.0.0"
warning Resolution field "[email protected]" is incompatible with requested version "unist-util-visit-parents@^4.0.0"
[2/4] π Fetching packages...
[###############################################################################################################################################################-] 797/[###############################################################################################################################################################-] 798/[#############info @next/[email protected]: The CPU architecture "x64" is incompatible with this module.
info "@next/[email protected]" is an optional dependency and failed compatibility check. Excluding it from installation.
info @next/[email protected]: The platform "darwin" is incompatible with this module.
info "@next/[email protected]" is an optional dependency and failed compatibility check. Excluding it from installation.
info @next/[email protected]: The platform "darwin" is incompatible with this module.
info "@next/[email protected]" is an optional dependency and failed compatibility check. Excluding it from installation.
[3/4] π Linking dependencies...
warning " > [email protected]" has unmet peer dependency "@popperjs/core@^2.10.1".
warning "next > styled-jsx > @babel/[email protected]" has unmet peer dependency "@babel/core@^7.0.0-0".
warning " > [email protected]" has unmet peer dependency "@types/node@*".
[4/4] π¨ Building fresh packages...
β¨ Done in 15.69s.
nick@Nicks-MBP handbook % yarn start
yarn run v1.22.11
$ next start
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
Error: Could not find a production build in the '/Users/nick/dev/handbook/.next' directory. Try building your app with 'next build' before starting the production server. https://nextjs.org/docs/messages/production-start-no-build-id
at Server.readBuildId (/Users/nick/dev/handbook/node_modules/next/dist/server/next-server.js:1573:23)
at new Server (/Users/nick/dev/handbook/node_modules/next/dist/server/next-server.js:92:29)
at NextServer.createServer (/Users/nick/dev/handbook/node_modules/next/dist/server/next.js:107:16)
at async /Users/nick/dev/handbook/node_modules/next/dist/server/next.js:119:31
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
A lot of the links on https://handbook.sourcegraph.com/company/team/org_chart are broken - possibly something to do with the auto-generated redirects and nested lists? For instance, the "Code graph" link goes to https://handbook.sourcegraph.com/company/team/code-graph but should be https://handbook.sourcegraph.com/engineering/code-graph.
Every time a candidate asks, I have to spend time talking about something I am not an expert in. A lot of candidates read our handbook thoroughly so if we had this documented it would save me time and I think it would give confidence to candidates that we know what we are doing here.
From today's kickoff meeting:
The strategy seems to be all about us, which isn't necessarily bad, but can we add sample problems that exist in each section and how either we actively are working on them with customers now, or how we plan on tackling these in the future?
This entails expanding the https://about.sourcegraph.com/company/strategy page.
"If there is a 1% chance that a swag package will help close a deal, that is the number 1 priority" - should be documented in the handbook
Add the ability to see backlinks for each page. In other words, "What links to this page?" (Locally, that is. From within the handbook, not links from external sites.)
We currently render the org chart by compiling all team pages' "Members" sections.
That is not a bad approach per se, but we do it all in the client at load time, which is noticeable and breaks often. For example, we currently seem to be adding a footer in the middle of the page, and date/time hover tooltips don't work in the dynamic content. The content can also not be searched I assume.
If we want to continue with this, we should look into doing this at build time. But also we should think about what the "ideal" org chart would look like for our handbook βΒ perhaps data taken from the BambooHR API. Perhaps even a real chart (although those don't necessarily scale better, rather the opposite).
We have documentation for creating a new page, but not for creating a directory. Will add this to existing "creating a new page" documentation.
Slashes /
are removed rather than converted into -
in anchors.
For example, on pages like the Teammates page, the she/her
is converted into sheher
instead of the previous she-her
, which breaks existing links to team members using this format.
The Table of contents in the right sidebar of the Handbook should only include h2 level headings as prescribed in the design here.
There's a "set heading ID" syntax from docsite, which is used in several places:
The expected behavior is to set the id (also known as the heading slug, or the hash fragment that points to it) for that element.
The actual behavior right now is that this is accidentally being parsed by the Slack channel plugin.
This would be a big rebase and we would freeze the handbook in the meantime on the about page.
Simplify and update handbook usage page. It's long and a bit cumbersome, and should reflect the views of the current handbook team + product maturity.
The createRelativeProductionLink
function does what it says, and makes an absolute link for a page (coming from the .yaml files) relative to the product home page.
handbook/src/lib/generatedMarkdown.js
Line 13 in 406e0c3
This works fine for content which is included from the product home page, but if you were to include content from anywhere else that needs relative links, it will break. It isn't breaking anything yet, because nobody is doing that.
This function should be made generic to take an absolute link, the absolute path to the current page, and generate a relative link on the fly.
Depends on #1
For sponsoring events and advertising our jobs.
See sourcegraph/about#327 for context
This is very minor, but when you use the search bar on a preview build on Netlify, the links in the results are sending back to the production website.
That can be easily overlooked if you don't pay attention though!
I'm going to add design QA items here, with the idea that some things may already be in progress/resolved with other work, and we can break out anything that's needed into a separate issue.
color: #24292e;
inherited from .markdown-body
instead of the --text-color
var defined in body
./
in breadcrumbs should be gray-06
.40px
/ 2.5rem
, and spacing between header bar and in-page navigation should increase to match.Using relative links is critical to make sure that the handbook can be browsed on deploy previews in PRs and on old revisions. It can be unintuitive for people not familiar with the concept though, which is why we have this handbook page: https://handbook.sourcegraph.com/editing/linking-within-handbook
Our link checker cannot check for this directly, but we could add a step that simply does a grep
for links looking like [...](https://handbook.sourcegraph.com/...)
in the content/
directory.
Before the recent changes to the Handbook link checks (which were a big improvement!), a user could see which file contained the broken link right there within the check.
Now, the error tells the user which link is broken, but not where that link is:
The user can find the page with the broken link by looking at the "files changed" tab on their PR. Is it possible to re-expose that information on the handbook check failure? It's a little confusing as is.
Context in this thread.
Examples:
Some do work:
Perhaps we missed a folder or file type, looking at the old paths? Example: https://sourcegraph.com/github.com/sourcegraph/about/-/commit/3f75bff1c2eb936cb8ab2066b79ff27796107b12?visible=1
We discovered this issue in #244: prettier
can change the Markdown syntax in ways that markdown-link-check
seems to be unable to handle, especially when there are image or regular links with parentheses (or, I presume, other characters that cause issues in regular Markdown link syntax). Here's the original Slack thread if extra context is needed.
As a simple example, let's say we're linking to https://example.com/image(1).png
, and we have this Markdown:
![my awesome image](https://example.com/image(1).png)
Prettier will then use angled brackets to escape the link:
![my awesome image](<https://example.com/image(1).png>)
At which point markdown-link-check
doesn't know how to handle that syntax, returns a 400, and the test fails. Oops.
I'm not really familiar enough with this to have a good idea on the right place to change this: if Prettier has an option to URL encode instead of surrounding with angled brackets, that would probably work. Or maybe there's an option or fix for markdown-link-check
to make this work.
We haven't added a rehype plugin for syntax highlighting + CSS theme file yet.
Not the highest priority since we don't have as many code blocks in the handbook, but we do have some.
There are multiple options available, might be worth a quick research which is the most modern/considered best nowadays: https://github.com/rehypejs/rehype/blob/main/doc/plugins.md
When I edit the handbook it is unclear how or when the change will be deployed. The ideal state is that a green build on the main branch means that the commit has been deployed.
Somewhat related to objection handling, but not exactly the same. Discussed this with @chrisdelane today after a call. I have a lot of qualification questions in my head, and what the pitch is depending on the result, and I (and @sqs ) should document these. E.g.:
Does your org use microservices or a monorepo?
What languages does your org use?
Is your team all co-located or remote?
Etc.
This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.
These problems occurred while renovating this repository. View logs.
Warning
These dependencies are deprecated:
Datasource | Name | Replacement PR? |
---|---|---|
npm | @types/mkdirp |
|
npm | hast |
|
npm | mdast |
These updates are awaiting their schedule. Click on a checkbox to get an update now.
These updates have been manually edited so Renovate will no longer make changes. To discard all commits and start over, click on a checkbox.
@types/hast
, @types/mdast
, @types/node
, node
)remark-github
, remark-parse
)creyD/prettier_action
, prettier
)remark-gfm
, remark-github
, remark-parse
, remark-rehype
)These updates have all been created already. Click a checkbox below to force a retry/rebase of any.
These are blocked by an existing closed PR and will not be recreated unless you click a checkbox below.
node
, @types/node
)react
, react-dom
).tool-versions
node 18.9.0
pnpm 8.1.1
Dockerfile
node latest
.github/workflows/build-handbook.yml
actions/checkout v3
actions/setup-node v3
.github/workflows/codenotify.yml
actions/checkout v3
sourcegraph/codenotify v0.4
.github/workflows/data-validation.yml
actions/checkout v3
actions/setup-node v3
.github/workflows/large-files.yml
actions/checkout v3
Amadevus/pwsh-script v2
macos 11
.github/workflows/link-check.yml
actions/checkout v3
actions/setup-node v3
.github/workflows/notion-migration.yaml
actions/github-script v6
.github/workflows/pr-title.yml
morrisoncole/pr-lint-action v1.5.1
.github/workflows/prettier.yml
actions/checkout v3
actions/setup-node v3
creyD/prettier_action v3.3
.github/workflows/stale.yml
actions/stale v4
.github/workflows/update-branches.yml
actions/checkout v3
package.json
@agentofuser/rehype-section ^1.0.5
@stefanprobst/rehype-extract-toc ^2.1.1
@types/js-yaml 4.0.5
@types/mkdirp 1.0.2
@types/unist 2.0.6
bootstrap ^5.1.3
chrono-node ^2.3.2
date-fns ^2.25.0
execa ^5.1.1
gitlog ^4.0.4
gray-matter ^4.0.3
hast-util-find-and-replace ^4.0.0
hast-util-is-element ^2.1.1
hast-util-to-string ^2.0.0
hastscript ^7.1.0
highlight.js ^11.3.1
js-yaml ^4.1.0
mdi-react ^8.1.0
mkdirp ^1.0.4
next ^12.0.2
next-seo ^4.28.1
react ^17.0.2
react-dom ^17.0.2
rehype-autolink-headings ^6.1.0
rehype-highlight ^6.0.0
rehype-raw ^6.1.0
rehype-slug ^5.0.0
rehype-stringify ^9.0.2
rehype-url-inspector ^2.0.2
relateurl ^0.2.7
remark-extract-toc ^1.1.0
remark-gfm ^3.0.1
remark-github ^11.2.1
remark-parse ^10.0.0
retext ^8.1.0
retext-smartypants ^5.1.0
tippy.js ^6.3.5
ts-node ^10.4.0
unified ^10.1.0
unist-util-visit ^4.1.0
vfile ^5.2.0
@actions/core ^1.6.0
@sourcegraph/eslint-config ^0.26.0
@sourcegraph/prettierrc ^3.0.3
@sourcegraph/tsconfig ^4.0.1
@types/hast ^2.3.4
@types/line-column 1.0.0
@types/mdast ^3.0.10
@types/node ^18.11.18
@types/react 18.0.0
@types/relateurl 0.2.29
ajv-cli ^5.0.0
chalk ^4.1.2
eslint ^7.32.0
globby ^11.1.0
hast ^1.0.0
hast-util-select ^5.0.5
jest ^27.4.5
line-column ^1.0.2
markdown-link-check ^3.8.7
mdast ^3.0.0
next-sitemap ^3.1.16
prettier ^2.8.3
rehype ^12.0.1
remark-rehype ^10.1.0
sass ^1.43.4
strip-ansi ^7.0.1
typescript ^4.4.4
node ^v18.9.0
pnpm ^8
unist-util-is 5.1.1
unist-util-visit-parents 5.1.0
pnpm 8.1.1
Move content from https://docs.google.com/document/d/1t-8vkc5htSAH7wfm5biZ5xUP-pKP8jV7oaxJ-zNp8ZA/edit#heading=h.czllfqbqit6z into the marketing section of the handbook.
Our content guidelines say to always use typographic quotation marks.
This would be best facilitated by the smartypants plugin, which does this automatically.
There is a retext plugin which should be possible to be used with rehype-retext
(which allows to use retext plugins), but when I tried it, I got an error that it expects a Parser
to be passed. I have a hunch that it is not compatible with the newest remark versions and needs some updates (probably super minor ones).
We have infrastructure in the handbook that emits markdown at build time (yarn generated-pages
) but it would be cleaner if we supported MDX to fill the content from the data files, as well as bring the possibility of other automation to the handbook.
The biggest immediate benefit is that it would allow content fills to be used on-page anywhere, mixing markdown and generated content, instead of only allowing for entirely generated pages.
It would also allow for possibilities of improvements like #649.
The video at https://handbook.sourcegraph.com/editing/linking-within-handbook is missing captions.
Captions can be added to this video following the guide at https://handbook.sourcegraph.com/marketing/adding_screenshots_screen_recording#adding-captions-for-your-voice-over-to-your-video
A declarative, efficient, and flexible JavaScript library for building user interfaces.
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. πππ
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google β€οΈ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.