Skip to content

Commit

Permalink
Move wiki page about codespaces and dev container into normal docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Aaron-Junker committed Oct 19, 2023
1 parent 129c6c7 commit 434e1aa
Show file tree
Hide file tree
Showing 5 changed files with 73 additions and 2 deletions.
2 changes: 1 addition & 1 deletion docs/docs/contribute/contributing-guide.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 6 additions & 0 deletions docs/docs/contribute/environment-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
60 changes: 60 additions & 0 deletions docs/docs/contribute/github-codespaces-and-devcontainer.mdx
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion docs/docs/contribute/new-command/build-command-logic.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
5 changes: 5 additions & 0 deletions docs/src/config/sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -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': [
{
Expand Down

0 comments on commit 434e1aa

Please sign in to comment.