docs: Move guides into its own section/sidebar. Start on new blog. (#304

) * Make guides its own section. * Add changelog. * Update blog. * Fix build. * Disable guides in navbar. * Update docusaurus. * Update blog. * Add run report action. * Bump * Log env vars. * Add quotes. * Bump * Bump * Add matrix info. * Bump * Bump * Bump * Finalize docs.
moonrepo · Sep 14, 2022 · 493f508 · 493f508
1 parent 06257ca
commit 493f508
Show file tree

Hide file tree

Showing 17 changed files with 411 additions and 258 deletions.
diff --git a/.github/workflows/moon.yml b/.github/workflows/moon.yml
@@ -61,3 +61,7 @@ jobs:
         with:
           command: run
           args: -- --color --log trace ci --base ${{ github.base_ref || 'master' }}
+      - uses: moonrepo/run-report-action@v1
+        with:
+          access-token: ${{ secrets.GITHUB_TOKEN }}
+          matrix: ${{ toJSON(matrix) }}
diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+#### 🎉 Release
+
+- Released a new GitHub action,
+  [`moonrepo/run-report-action`](https://github.com/marketplace/actions/moon-ci-run-reports)!
+
 #### 💥 Breaking
 
 - Reworked how caching/hashing works when running in a Docker container/image. If the VCS root
@@ -10,11 +15,18 @@
 
 #### 🚀 Updates
 
+- Added a new `moon generate` command, for code generation and scaffolding.
+- Added a `generator` setting to `.moon/workspace.yml`, for controlling aspects of the generator and
+  its templates.
 - Updated the project graph to scan and find implicit dependencies based on language specific
-  semantics. For example, will determine moon projects based on `package.json` names and
-  dependencies.
+  semantics. For example, will determine moon project relationships based on `package.json` names
+  and dependencies.
 - Updated `moon setup` to also install Node.js dependencies.
 
+#### 🐞 Fixes
+
+- Fixed an issue where project and task names were not being cleaned/formatted properly.
+
 ## 0.13.0
 
 #### 💥 Breaking
@@ -58,7 +70,8 @@
 
 - Added support for Linux ARM GNU (`aarch64-unknown-linux-gnu`).
 - Added support for Linux ARM musl (`aarch64-unknown-linux-musl`).
-- Added a `typescript` setting to `moon.yml`, allowing TypeScript support to be toggled per project.
+- Added a `workspace.typescript` setting to `moon.yml`, allowing TypeScript support to be toggled
+  per project.
 - Added a `--report` option to the `moon run` command, for generating run reports for debugging.
 - Added an `--affected` option to the `moon query projects` command.
 - Updated the task `command` to also support inline arguments. You can now merge `command` and

diff --git a/website/blog/2022-09-01_v0.13.md → website/blog/2022-09-01_v0.13.mdx b/website/blog/2022-09-01_v0.13.md → website/blog/2022-09-01_v0.13.mdx
@@ -1,7 +1,6 @@
 ---
 slug: v0.13
 title: v0.13 - Hashing and toolchain improvements
-description: This is my first post on Docusaurus 2.
 authors: [milesj]
 tags: [hasher, toolchain]
 ---
@@ -92,7 +91,7 @@ full list of changes.
 
 Expect the following in the v0.14 release!
 
-- A `moon new` command to generate new projects, files, scaffolding, and more from pre-defined
+- A `moon generate` command to generate new projects, files, scaffolding, and more from pre-defined
   templates.
 - Implicit dependency discovery. moon will now scan manifest files and determine project
   relationships.
diff --git a/website/blog/2022-09-14_v0.14.mdx b/website/blog/2022-09-14_v0.14.mdx
@@ -0,0 +1,72 @@
+---
+slug: v0.14
+title: v0.14 - Code generation and implicit dependencies
+authors: [milesj]
+tags: [generator, project-graph, ci]
+---
+
+import Image from '@site/src/components/Image';
+
+With this release, we've landed some new features that have been requested multiple times since
+launch. A code generation and template scaffolding layer, as well as implicit dependency scanning
+for the project graph!
+
+<!--truncate-->
+
+## New `moon generate` command
+
+Code generation is the staple of any large company or repository. Want to spin up a new application?
+What about an npm package? Or maybe third-party integrations? Avoid copy-and-pasting existing code,
+and instead generate it with the new `moon generate` command, which is powered by our new generator
+system.
+
+The generator will locate a template by name on the file system ("npm-package" in the example
+below), prompt and interpolate variables, render the files with [Tera](https://tera.netlify.app/) (a
+Rust based template engine), and write the files to the target destination.
+
+```shell
+# Generate code from a template to a target directory
+$ moon generate npm-package ./packages/example
+```
+
+Learn more about [code generation in the official guide](../docs/guides/codegen)!
+
+## Implicit dependency scanning
+
+This has been a request since moon's official release, and it's finally here! Up until now, if you
+wanted project-to-project dependency relationships, you had to explicitly declare them with
+[`dependsOn`](../docs/config/project#dependson). But thanks to a
+[ton of](https://github.com/moonrepo/moon/pull/288)
+[infrastructure](https://github.com/moonrepo/moon/pull/249) and
+[platform](https://github.com/moonrepo/moon/pull/277) changes, we can now infer implicit
+dependencies automatically!
+
+We still suggest using explicit dependencies, as it provides more
+[automation like project syncing](../docs/concepts/project#dependencies), but implicit is great for
+adoption and migration purposes.
+
+## Report CI runs on pull requests
+
+We're fans of continuous and easily accessible feedback, and as such, have released a new GitHub
+action, [`moonrepo/run-report-action`](https://github.com/marketplace/actions/moon-ci-run-reports),
+which reports the results of [`moon ci`](../docs/commands/ci) as a pull request comment. The report
+looks something like the following:
+
+<Image src={require('../static/img/github/run-report.png')} width="60%" />
+
+## Other changes
+
+View the
+[official release](https://github.com/moonrepo/moon/releases/tag/%40moonrepo%2Fcli%400.14.0) for a
+full list of changes.
+
+- When running in a Docker container, caching is disabled in an effort to greatly reduce the size of
+  the image.
+- Updated `moon setup` to also install Node.js dependencies.
+
+## What's next?
+
+Expect the following in the v0.15 release!
+
+- Webhooks! Receive messages for all events in the action runner.
+- Major Docker workflow improvements!
diff --git a/website/docs/faq.mdx b/website/docs/faq.mdx
@@ -4,6 +4,24 @@ title: FAQ
 
 ## General
 
+### Where did the name "moon" come from?
+
+The first incarnation of the name was a misspelling of monorepo (= moonrepo). This is where the
+domain moonrepo.dev came from, and our official company, moonrepo LLC.
+
+However, moonrepo is quite a long name with many syllables, and as someone who prefers short 1
+syllable words, moon was perfect. The word moon also has great symmetry, as you can see in our logo!
+
+But that's not all... moon is also an acronym. It originally stood for **m**onorepo,
+**o**rganization, **o**rchestration, and **n**otification tool. But since moon can also be used for
+polyrepos, we replaced monorepo with **m**anagement (as shown on the homepage). This is a great
+acronym, as it embraces what moon is trying to solve:
+
+- **M**anage repos, projects, and tasks with ease.
+- **O**rganize projects and the repo to scale.
+- **O**rchestrate tasks as efficiently as possible.
+- **N**otify developers and systems about important events.
+
 ### Will moon support other languages besides JavaScript?
 
 Yes! Although we're focusing right now on JavaScript (and TypeScript, Node.js), we've designed moon
@@ -12,6 +30,12 @@ to be language agnostic and easily pluggable in the future.
 If we're to guess which language would be next, it would most likely be Ruby to support React Native
 based applications.
 
+### Will moon support continuous deployment?
+
+Yes! We plan to integrate CD with the current build and CI system, but we are focusing on the latter
+2 for the time being. Why not start using moon today so that you can easily adopt CD when it's
+ready?
+
 ### What should be considered the "source of truth"?
 
 If you're a frontend developer, you'll assume that a `package.json` is the source of truth for a

diff --git a/website/docs/guides/ci.mdx b/website/docs/guides/ci.mdx
@@ -4,6 +4,7 @@ title: Continuous integration (CI)
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import Image from '@site/src/components/Image';
 
 All companies and projects rely on continuous integration (CI) to ensure high quality code and to
 avoid regressions. Because this is such a critical piece of every developer's workflow, we wanted to
@@ -228,3 +229,28 @@ script: 'moon ci --job $TRAVIS_JOB_INDEX --jobTotal $TRAVIS_JOB_TOTAL'
 </Tabs>
 
 > Your CI environment may provide environment variables for these 2 values.
+
+## Reporting run results
+
+If you're using GitHub Actions as your CI provider, we suggest using our
+[`moonrepo/run-report-action`](https://github.com/marketplace/actions/moon-ci-run-reports). This
+action will report the results of a [`moon ci`](../commands/ci) run to a pull request as a comment
+and workflow summary.
+
+```yaml title=".github/workflows/ci.yml"
+# ...
+jobs:
+  ci:
+    name: 'CI'
+    runs-on: 'ubuntu-latest'
+    steps:
+      # ...
+      - run: 'yarn moon ci'
+      - uses: 'moonrepo/run-report-action@v1'
+        with:
+          access-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+The report looks something like the following:
+
+<Image src={require('../../static/img/github/run-report.png')} width="60%" />
diff --git a/website/docs/guides/codegen.mdx b/website/docs/guides/codegen.mdx
@@ -1,5 +1,5 @@
 ---
-title: Generating code
+title: Code generation
 toc_max_heading_level: 6
 tags: [codegen, generator, scaffold, template]
 ---
@@ -80,8 +80,8 @@ documentation for an in-depth understanding, but as a quick reference, Tera supp
   [built-in filters](https://tera.netlify.app/docs/#built-ins).
 
 ```twig
-{{ varName }} # foo
-{{ varName | upper }} # FOO
+{{ varName }} -> foo
+{{ varName | upper }} -> FOO
 ```
 
 - [Conditional blocks](https://tera.netlify.app/docs/#if) and
@@ -103,7 +103,7 @@ documentation for an in-depth understanding, but as a quick reference, Tera supp
 {% endfor %}
 ```
 
-- And many more features, like auto-escaping, white space control, math operators!
+- And many more features, like auto-escaping, white space control, and math operators!
 
 #### Filters
 
@@ -177,7 +177,7 @@ share templates across repositories? Why not try...
 
 - git submodules
 - npm packages
-- other packaging system
+- another packaging system
 
 Regardless of the choice, simply configure [`generator.templates`][gen-templates] to point to these
 locations:

diff --git a/website/docs/guides/profile.mdx b/website/docs/guides/profile.mdx
@@ -1,5 +1,5 @@
 ---
-title: Profiling tasks
+title: Task profiling
 ---
 
 import Image from '@site/src/components/Docs/Image';

diff --git a/website/docs/migrate-to-moon.mdx b/website/docs/migrate-to-moon.mdx
@@ -58,7 +58,7 @@ following risks and disadvantages:
 ## Next steps
 
 By this point, you should have a better understanding behind moon's fundamentals! Why not adopt
-incrementally next? Jump into [guides](./guides) for advanced use cases or [concepts](./concepts)
+incrementally next? Jump into [guides](./guides/ci) for advanced use cases or [concepts](./concepts)
 for a deeper understanding.
 
 <NextSteps

diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
@@ -82,16 +82,22 @@ const config = {
 					src: 'img/logo.svg',
 				},
 				items: [
+					{
+						to: '/blog',
+						label: 'Blog',
+						position: 'left',
+					},
 					{
 						type: 'doc',
 						docId: 'intro',
 						position: 'left',
 						label: 'Docs',
 					},
 					{
-						to: '/blog',
-						label: 'Blog',
+						type: 'doc',
+						docId: 'guides/ci',
 						position: 'left',
+						label: 'Guides',
 					},
 					{
 						to: '/api',
@@ -110,6 +116,10 @@ const config = {
 								label: '@moonrepo/dev',
 								href: 'https://www.npmjs.com/package/@moonrepo/dev',
 							},
+							{
+								label: '@moonrepo/types',
+								href: 'https://www.npmjs.com/package/@moonrepo/types',
+							},
 							{
 								label: 'babel-preset-moon',
 								href: 'https://www.npmjs.com/package/babel-preset-moon',
@@ -145,16 +155,20 @@ const config = {
 						title: 'Learn',
 						items: [
 							{
-								label: 'Documentation',
+								label: 'Blog',
+								to: '/blog',
+							},
+							{
+								label: 'Docs',
 								to: '/docs',
 							},
 							{
-								label: 'API',
-								to: '/api',
+								label: 'Guides',
+								to: '/docs/guides/ci',
 							},
 							{
-								label: 'Examples repository',
-								href: 'https://github.com/moonrepo/examples',
+								label: 'API',
+								to: '/api',
 							},
 						],
 					},
@@ -170,9 +184,13 @@ const config = {
 								to: 'https://github.com/moonrepo/moon/discussions',
 							},
 							{
-								label: 'Configurations',
+								label: 'Tooling configs',
 								href: 'https://github.com/moonrepo/dev',
 							},
+							{
+								label: 'Examples repository',
+								href: 'https://github.com/moonrepo/examples',
+							},
 						],
 					},
 					{

diff --git a/website/moon.yml b/website/moon.yml
@@ -9,26 +9,20 @@ dependsOn:
 
 tasks:
   build:
-    command: 'docusaurus'
-    args: 'build'
+    command: 'docusaurus build'
     deps:
       - '^:build'
     outputs:
       - 'build'
 
   start:
-    command: 'docusaurus'
-    args: 'start'
+    command: 'docusaurus start'
     deps:
       - '^:build'
     local: true
 
   typecheck:
-    command: 'tsc'
-    args:
-      - '--build'
-      - '--pretty'
-      - '--verbose'
+    command: 'tsc --build --pretty --verbose'
     inputs:
       - '@globs(sources)'
       - '*.js'

diff --git a/website/package.json b/website/package.json
@@ -14,9 +14,9 @@
     "write-translations": "docusaurus write-translations"
   },
   "dependencies": {
-    "@docusaurus/core": "^2.0.1",
-    "@docusaurus/preset-classic": "^2.0.1",
-    "@docusaurus/theme-common": "^2.0.1",
+    "@docusaurus/core": "^2.1.0",
+    "@docusaurus/preset-classic": "^2.1.0",
+    "@docusaurus/theme-common": "^2.1.0",
     "@fortawesome/fontawesome-svg-core": "^6.1.1",
     "@fortawesome/free-brands-svg-icons": "^6.1.1",
     "@fortawesome/pro-duotone-svg-icons": "^6.1.1",
@@ -30,7 +30,7 @@
     "react-dom": "^17.0.2"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.1",
+    "@docusaurus/module-type-aliases": "^2.1.0",
     "@moonrepo/runtime": "workspace:^",
     "@moonrepo/types": "workspace:^",
     "@tsconfig/docusaurus": "^1.0.6",