From 434e1aa8cbc5740d0db30c4c5d6bcc26baef3811 Mon Sep 17 00:00:00 2001 From: Aaron Junker Date: Thu, 19 Oct 2023 20:50:54 +0200 Subject: [PATCH 1/2] Move wiki page about codespaces and dev container into normal docs --- docs/docs/contribute/contributing-guide.mdx | 2 +- docs/docs/contribute/environment-setup.mdx | 6 ++ .../github-codespaces-and-devcontainer.mdx | 60 +++++++++++++++++++ .../new-command/build-command-logic.mdx | 2 +- docs/src/config/sidebars.js | 5 ++ 5 files changed, 73 insertions(+), 2 deletions(-) create mode 100644 docs/docs/contribute/github-codespaces-and-devcontainer.mdx diff --git a/docs/docs/contribute/contributing-guide.mdx b/docs/docs/contribute/contributing-guide.mdx index a9fc951f31f..2365d9840cc 100644 --- a/docs/docs/contribute/contributing-guide.mdx +++ b/docs/docs/contribute/contributing-guide.mdx @@ -33,7 +33,7 @@ Typos are embarrassing! Most PRs that fix typos will be accepted immediately. To ## Contribution paths -Before you start contributing, it's important to ensure that your environment is set up correctly. You can refer to the extensive guide on how to achieve this: [Setting up your environment](./environment-setup.mdx). +Before you start contributing, it's important to ensure that your environment is set up correctly. We recommend you to use GitHub Codespaces or our dev container described in this guide: [GitHub Codespaces & Visual Studio Remote Development Container](./github-codespaces-and-devcontainer.mdx). Alternatively, you can refer to the extensive guide on how to achieve this locally: [Setting up your environment](./environment-setup.mdx). ### Adding a new command diff --git a/docs/docs/contribute/environment-setup.mdx b/docs/docs/contribute/environment-setup.mdx index 8b077b56a40..1007d751fe7 100644 --- a/docs/docs/contribute/environment-setup.mdx +++ b/docs/docs/contribute/environment-setup.mdx @@ -8,6 +8,12 @@ Before you start contributing to this project, you will need **node@18** and **n ::: +:::tip + +To avoid having to install all dependencies by hand you can use Github Codespaces or our dev container. More information can be found under [GitHub Codespaces & Visual Studio Remote Development Container](./github-codespaces-and-devcontainer.mdx). + +::: + ## Getting your local version of the CLI ### Setting up your GitHub fork diff --git a/docs/docs/contribute/github-codespaces-and-devcontainer.mdx b/docs/docs/contribute/github-codespaces-and-devcontainer.mdx new file mode 100644 index 00000000000..ea93ad9d6ad --- /dev/null +++ b/docs/docs/contribute/github-codespaces-and-devcontainer.mdx @@ -0,0 +1,60 @@ +# GitHub Codespaces & Visual Studio Remote Development Container + +One of the difficulties of getting started with a new project is setting up the development environment, installing dependencies and hoping that you've followed all the instructions correctly. + +We know that this can be time-consuming and also put off potential contributors to the project, so we've looked at ways in which we can make contributor onboarding as simple as possible, so we have provided a definition for creating an instant development environment that contains all the dependencies needed to contribute to CLI for Microsoft 365, whether that is making code changes or making an update to the documentation, we have you covered. + +Our development environments contain the following dependencies + +* Ubuntu 20.04 inc. sudo, zsh, jq, curl, git & wget +* PowerShell (7.1.0) +* node (v18.16.1) & npm (9.1.2) +* Python3 (3.10) & pip3 (22.3.1) +* oh-my-zsh (zsh-in-docker) +* zsh-autosuggestions +* zsh-completions +* zsh-syntax-highlighting +* spaceship-prompt + +We've also bundled the following Visual Studio Code extensions in the container + +* ESLint +* Test Explorer UI +* Mocha Test Explorer +* GitLens + +We also automate the initial configuration steps for you when the development environment is being created, so we run npm install to install the necessary packages from npm, npm run build to build the CLI source and create a symbolic link by running npm link to ensure that when you execute m365 it uses the code in the src directory. + +You can use our development environment in the cloud using GitHub Codespaces or locally using Visual Studio Code Remote Development Containers. + +## GitHub Codespaces + +GitHub Codespaces is an online development environment, hosted by GitHub and powered by Visual Studio Code, that allows you to develop entirely in the cloud. + +To create an instant environment to develop and test the CLI. + +* Fork this repository +* On GitHub, navigate to the main page of the repository +* Under the repository name, use the Branch drop-down menu, and select the branch you want to create a codespace for +* Under the repository name, use the Code drop-down menu, and select Open with Codespaces +* Click New codespace + +## Local Remote Development Container + +You may also use the development environment definition locally using Visual Studio Code. + +To build and use a remote development container for local development, you first need the below prerequisites installed. + +* Visual Studio Code +* Docker Desktop +* Remote Containers extension + +Once the prerequisites are installed + +* Fork this repository +* Clone your forked repository locally +* Open the repository in Visual Studio Code +* You will receive prompt Folder contains a remote development container +* Click Reopen in Container to build the remote development container and start the instant development environment + +The initial build time will vary depending on your machine, but is a one-time operation (unless we change the container in the future) so the next time you run the CLI in a remote development container the build step will not be required. diff --git a/docs/docs/contribute/new-command/build-command-logic.mdx b/docs/docs/contribute/new-command/build-command-logic.mdx index d8a2892510d..ecf16c131cb 100644 --- a/docs/docs/contribute/new-command/build-command-logic.mdx +++ b/docs/docs/contribute/new-command/build-command-logic.mdx @@ -276,7 +276,7 @@ In the end, your command file will look something like this: [group-get.ts](http Before creating a PR, you should test your code locally. This will help you catch bugs, errors, and performance issues early on and ensure that the code functions as intended before it is made available to real users. You can execute `npm run watch` to start a live watcher. This will build the entire project first, and after that, a watcher will ensure that every time a file is saved, an incremental build is triggered. This means that not the entire project is rebuilt, but only the changed files. This makes it easy to make quick changes and test them immediately after saving them. -If this command fails, be sure to check if your environment has been set up correctly following the guidelines of [Setting up your local project](../environment-setup.mdx#setting-up-your-local-project). +If this command fails, be sure to check if your environment has been set up correctly following the guidelines of [Setting up your local project](../environment-setup.mdx#setting-up-your-local-project) or if you use a dev container or GitHub Codespaces: [GitHub Codespaces & Visual Studio Remote Development Container](./github-codespaces-and-devcontainer.mdx). ## Next step diff --git a/docs/src/config/sidebars.js b/docs/src/config/sidebars.js index 28f8a409d37..0f83e3239c9 100644 --- a/docs/src/config/sidebars.js +++ b/docs/src/config/sidebars.js @@ -4219,6 +4219,11 @@ const sidebars = { label: 'Environment setup', id: 'contribute/environment-setup' }, + { + type: 'doc', + label: 'GitHub Codespaces & dev container setup', + id: 'contribute/github-codespaces-and-devcontainer' + }, { 'Creating a new command': [ { From 00d450633c8f40940ef3351f8aedba1fc9ad3e67 Mon Sep 17 00:00:00 2001 From: Aaron Junker Date: Sat, 28 Oct 2023 20:01:08 +0000 Subject: [PATCH 2/2] Fix link --- docs/docs/contribute/new-command/build-command-logic.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/contribute/new-command/build-command-logic.mdx b/docs/docs/contribute/new-command/build-command-logic.mdx index ecf16c131cb..0976b06df89 100644 --- a/docs/docs/contribute/new-command/build-command-logic.mdx +++ b/docs/docs/contribute/new-command/build-command-logic.mdx @@ -276,7 +276,7 @@ In the end, your command file will look something like this: [group-get.ts](http Before creating a PR, you should test your code locally. This will help you catch bugs, errors, and performance issues early on and ensure that the code functions as intended before it is made available to real users. You can execute `npm run watch` to start a live watcher. This will build the entire project first, and after that, a watcher will ensure that every time a file is saved, an incremental build is triggered. This means that not the entire project is rebuilt, but only the changed files. This makes it easy to make quick changes and test them immediately after saving them. -If this command fails, be sure to check if your environment has been set up correctly following the guidelines of [Setting up your local project](../environment-setup.mdx#setting-up-your-local-project) or if you use a dev container or GitHub Codespaces: [GitHub Codespaces & Visual Studio Remote Development Container](./github-codespaces-and-devcontainer.mdx). +If this command fails, be sure to check if your environment has been set up correctly following the guidelines of [Setting up your local project](../environment-setup.mdx#setting-up-your-local-project) or if you use a dev container or GitHub Codespaces: [GitHub Codespaces & Visual Studio Remote Development Container](./../github-codespaces-and-devcontainer.mdx). ## Next step