Minor editorial, grammatical, and spelling improvments to docs #1701
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎ 1 Ignored Deployment
|
|
Added "on-hold" just to prevent auto-merge. @mehulkar remove once you get your approvals |
This comment was marked as outdated.
This comment was marked as outdated.
|
|
||
| - Hash the contents of all not-gitignored files in the package folder or the files matching the `inputs` globs, if present | ||
| - Hash the contents of all version-controlled files in the package folder or the files matching the `inputs` globs, if present |
There was a problem hiding this comment.
Some feedback from @mirshko in https://github.com/orgs/vercel/discussions/780#discussioncomment-3409321, that we could probably incorporate into this section while I'm here
Co-authored-by: Maedah Batool <me@MaedahBatool.com>
|
I didn't dig into the previous requested changes, so if I'm suggesting anything contradictory, please ignore! |
Co-authored-by: Thomas Knickman <tom.knickman@vercel.com>
Co-authored-by: Thomas Knickman <tom.knickman@vercel.com>
Co-authored-by: Thomas Knickman <tom.knickman@vercel.com>
Co-authored-by: Thomas Knickman <tom.knickman@vercel.com>
| @@ -146,7 +144,7 @@ Luckily, you can control `turbo`'s cache fingerprinting (a.k.a. hashing) behavio | |||
| ``` | |||
|
|
|||
| <Callout type="info"> | |||
| Pro Tip: In most monorepos, you don't often use environment variables in shared packages, but mostly only in applications. Thus, to get higher cache hit rates, you should likely only include environment variables in the app-specific tasks where they are used/inlined. | |||
| Pro Tip: It is more common for monorepos to use environment variables in workspaces that contain applications (such as a website) rather than shared packages (such as a UI component library). Thus, to get higher cache hit rates, you should likely only "depend on" environment variables in package-specific tasks in your `turbo.json` configuration. | |||
There was a problem hiding this comment.
This is a really good rewording.
|
|
||
| - Hash the contents of all not-gitignored files in the package folder or the files matching the `inputs` globs, if present | ||
| - Hash the contents of all version-controlled files in the package folder or the files matching the `inputs` globs, if present |
There was a problem hiding this comment.
😅 This is actually a bit imprecise because of:
turborepo/cli/internal/taskhash/taskhash.go
Lines 101 to 102 in e7b7d68
That's something we should fix but that means spending more time plumbing commands through to ask git what it thinks of the world before doing our processing.
|
|
||
| To give you a sense of how powerful this can be, the below diagram compares the `turbo` vs `lerna` task execution timelines: | ||
| To give you a sense of how powerful this can be, the diagram below compares the `turbo` and `lerna` task execution timelines: |
There was a problem hiding this comment.
We should maybe revisit this diagram without framing it in the context of Lerna.
| </Tab> | ||
| <Tab> | ||
| ```bash | ||
| yarn add turbo --dev -W |
There was a problem hiding this comment.
In documentation I prefer not using shorthand flags. PR: #1767
| @@ -11,16 +11,16 @@ import { Tabs, Tab } from '../../../components/Tabs' | |||
|
|
|||
| Workspaces are a feature implemented by package managers to assist with working on multiple apps and packages in the same codebase. | |||
|
|
|||
| Turborepo is compatible with three package managers, [npm](https://docs.npmjs.com/cli/v8/using-npm/workspaces#description), [Yarn](https://classic.yarnpkg.com/lang/en/docs/workspaces/), and [pnpm](https://pnpm.io/workspaces), each with its own implementation of workspaces and functionality. Your package manager will determine how your apps and packages are organized in your workspaces and run in your turborepo. | |||
| Turborepo is compatible with three package managers ([npm](https://docs.npmjs.com/cli/v8/using-npm/workspaces#description), [Yarn 1](https://classic.yarnpkg.com/lang/en/docs/workspaces/), and [pnpm](https://pnpm.io/workspaces)), each with its own implementation of workspaces and functionality. Your package manager will determine how your apps and packages are organized in your workspaces and run in your turborepo. | |||
There was a problem hiding this comment.
We support Berry just fine if you actually don't use the primary Berry feature...
| - **Cloud caching**: Share a cloud build cache with your teammates and CI/CD for even faster builds. | ||
| - **Parallel execution**: Execute builds using every core at maximum parallelism without wasting idle CPUs. | ||
| - **Zero runtime overhead**: Turborepo doesn't interfere with your runtime code or touch your sourcemaps. It does what it does and then gets out of your way. | ||
| - **Task pipelines**: Define the relationships between your tasks and then let Turborepo optimize what to build and when. | ||
| - **Pruned subsets**: Speed up PaaS deploys by generating a subset of your monorepo with only what's needed to build a specific target. | ||
| - **Convention-based config**: Reduce complexity through convention. Fan out configuration with just a few lines of JSON. | ||
| - **Profile in your browser**: Generate build profiles and import them in Chrome or Edge to understand which tasks are taking the longest. | ||
| - **Profile in your browser**: Generate build profiles and view them in a browser to understand which tasks are taking the longest. |
There was a problem hiding this comment.
This was actually correct previously. This generates a file compatible with about:tracing in (most) Chromium-based browsers.
There was a problem hiding this comment.
You can load these trace files into a lot of things; I'm going to be less specific, but still provide context about what it is: #1768
| @@ -200,7 +200,7 @@ Defaults to `[]`. Tells `turbo` the set of files to consider when determining if | |||
| Setting this to a list of globs will cause the task to only be rerun when files matching those globs have | |||
| changed. This can be helpful if you want to, for example, skip running tests unless a source file changed. | |||
|
|
|||
| Specifying `[]` will cause the task to be rerun when any file changes. | |||
| Specifying `[]` will cause the task to be rerun when any version-controlled file in the workspace changes. | |||
There was a problem hiding this comment.
Same comment as above. We shouldn't change this since that is (at least aspirationally) what it should do.
Today I read all of turborepo.org/docs and attempted to make improvements based on my own understanding. This was mostly an exercise for myself to understand the product. If there are any changes here that aren't obviously improvements, factually incorrect, or problematic in some other way, please let me know and I can either pull them into a separate PR for more discussion or revert them entirely.
The goal of this PR is not to change any top level information architecture or create cause for debate, but to make cosmetic improvements that should be pretty easily mergeable!
Here's a list of other things I noticed while reading the docs: https://www.notion.so/vercel/Turborepo-Docs-Reading-Notes-6db4a7c38c29476986cfac67353e21ba