Skip to main content

VS Code Workspace

Purpose​

Visual Studio Code is the standard development environment for Cloudberrie engineering projects.

This guide defines the required workspace structure, account configuration, Git identity, extensions, terminal practices, and project-opening procedures used across Cloudberrie repositories.

Following a consistent workspace standard helps ensure that:

  • Projects behave consistently across developer machines.
  • Git commits use the correct Cloudberrie identity.
  • Source code formatting remains predictable.
  • Repository and branch information is visible.
  • New contributors can begin working with minimal setup differences.
  • Development, staging, and production workflows remain separated.

Standard Development Tool​

Cloudberrie uses:

Visual Studio Code

Download and install the latest stable version of Visual Studio Code from the official Microsoft distribution.

Developers should avoid using preview or insider builds for routine Cloudberrie work unless a project specifically requires them.

Cloudberrie Project Location​

Cloudberrie projects should be stored under the following parent directory on macOS:

/Users/cloudberrie/Documents/Cloudberrie/Projects

Current project examples include:

/Users/cloudberrie/Documents/Cloudberrie/Projects/cb-manual
/Users/cloudberrie/Documents/Cloudberrie/Projects/cb-website
/Users/cloudberrie/Documents/Cloudberrie/Projects/cb-studio-board

Each GitHub repository must have its own local folder.

Do not place multiple repositories inside one shared Git repository.

Opening a Project​

Always open the repository root folder in Visual Studio Code.

For example, to open the Cloudberrie Manual:

cd /Users/cloudberrie/Documents/Cloudberrie/Projects/cb-manual
code .

The folder opened in VS Code should contain project-level files such as:

.git
package.json
README.md
docs
src
static
docusaurus.config.ts
sidebars.ts

Opening only the docs, src, or another subfolder may prevent VS Code and Git extensions from detecting the full repository correctly.

GitHub Account Standard​

The Cloudberrie engineering GitHub account is:

GitHub username: cb-engops
GitHub sign-in email: accounts@cloudberrie.com

Use either the GitHub username or verified account email when signing in.

The email below is not used as the GitHub login identity:

engineering@cloudberrie.com

It is used as the Git commit author email.

Git Commit Identity​

All Cloudberrie engineering commits must use the approved Cloudberrie commit identity.

Verify the current configuration:

git config --global user.name
git config --global user.email

The email must be:

engineering@cloudberrie.com

Set the Git author configuration when required:

git config --global user.name "Cloudberrie Engineering"
git config --global user.email "engineering@cloudberrie.com"

Verify the configuration:

git config --global --list

Expected values:

user.name=Cloudberrie Engineering
user.email=engineering@cloudberrie.com

Do not use personal email addresses for commits to Cloudberrie repositories.

Repository Identity Check​

Before making changes, confirm that the current folder belongs to the intended repository.

Run:

git remote -v

For the Cloudberrie Manual, the remote should reference:

cloudberrie-studio/cb-manual

Also confirm the active branch:

git branch --show-current

Typical output:

develop

Check the complete repository status:

git status

This displays:

  • The active branch
  • Whether the local branch matches the remote branch
  • Modified files
  • Untracked files
  • Staged changes

Standard Branch Awareness​

VS Code displays the active Git branch in the lower-left status bar.

Before editing a project, verify that the active branch matches the intended workflow.

Cloudberrie uses the following branch model:

feature/*
    ↓
develop
    ↓
staging
    ↓
main

Branch purposes:

BranchPurpose
feature/*Isolated feature or documentation work
developIntegrated development environment
stagingPre-production testing and approval
mainProduction-ready source

Do not assume the active branch.

Always verify it with:

git branch --show-current

The following extensions are recommended for Cloudberrie engineering work.

Core Extensions​

ExtensionPurpose
ESLintJavaScript and TypeScript code quality
PrettierConsistent code formatting
GitLensGit history and file-level change visibility
GitHub Pull Requests and IssuesPull request and GitHub workflow support
Material Icon ThemeClear file and folder identification
EditorConfigShared editor formatting rules
Markdown All in OneMarkdown authoring and navigation
Markdown Preview EnhancedDocumentation preview support

Project-Specific Extensions​

Install only when required by the project:

ExtensionUse
FirebaseFirebase-related projects
Cloudflare WorkersCloudflare Workers and Wrangler projects
Thunder ClientAPI testing
REST ClientHTTP request testing
Tailwind CSS IntelliSenseTailwind CSS projects
DockerContainer-based projects

Avoid installing unnecessary extensions that add background processes, duplicate functionality, or require broad repository permissions.

Workspace Trust​

When opening a Cloudberrie repository for the first time, VS Code may ask whether the folder is trusted.

Select workspace trust only when:

  • The repository was cloned from the official cloudberrie-studio GitHub organization.
  • The repository remote has been verified.
  • The source has not been downloaded from an unknown third party.

Verify the repository before enabling workspace features:

git remote -v

Integrated Terminal​

Use the VS Code integrated terminal for routine engineering operations.

Open it using:

Terminal → New Terminal

or:

Control + `

The terminal should open at the repository root.

Verify the current path:

pwd

For the Cloudberrie Manual, the output should be:

/Users/cloudberrie/Documents/Cloudberrie/Projects/cb-manual

Do not run Git, npm, or build commands from the wrong project directory.

Standard Terminal Checks​

At the beginning of a work session, run:

pwd
git branch --show-current
git status
git pull origin develop

Use the appropriate branch name when working outside develop.

Before committing, run:

git status
git diff

Before pushing, run the project validation command.

For Docusaurus projects:

npm run build

For local development:

npm start

Node.js and npm Verification​

Check the installed versions:

node --version
npm --version

Cloudberrie projects must use versions compatible with the repository and deployment platform.

Do not upgrade Node.js, npm, Docusaurus, React, or other major dependencies during unrelated feature work.

Dependency upgrades must be handled as separate, reviewed changes.

File Editing Standards​

Use the following practices when modifying Cloudberrie projects:

  • Edit only files related to the assigned change.
  • Do not replace entire project folders unless the change has been reviewed.
  • Do not copy node_modules between projects.
  • Do not manually edit generated build folders.
  • Do not edit .docusaurus output files.
  • Do not edit the build folder directly.
  • Preserve existing file names and directory structure unless a planned migration requires changes.
  • Use lowercase, hyphen-separated names for documentation files.

Examples:

vscode-workspace.md
branch-strategy.md
cloudflare-deployment.md
release-promotion.md

Avoid:

VSCode Workspace.md
Branch_Strategy.md
cloudflareDeployment.md

Generated Files​

The following folders are generated and should not be manually maintained:

node_modules
.docusaurus
build

They should normally be excluded through .gitignore.

When troubleshooting stale generated output, they may be removed and recreated:

rm -rf .docusaurus
rm -rf build
npm run build

These cleanup commands should not be run routinely when the project is already working correctly.

Formatting​

Where supported, use Prettier for consistent formatting.

Recommended behavior:

  • Format files before saving or committing.
  • Preserve existing repository conventions.
  • Avoid large formatting-only changes mixed with functional changes.
  • Do not reformat unrelated files.

If format-on-save causes unexpected changes across the repository, disable it temporarily and format only the files being modified.

Source Control Panel​

The VS Code Source Control panel can be used to review:

  • Modified files
  • New files
  • Deleted files
  • Staged changes
  • File diffs

However, all important Git operations should remain understandable through terminal commands.

Before committing, confirm changes with:

git status
git diff

Never commit based only on the number shown in the VS Code Source Control icon.

Commit Workflow​

A standard documentation update follows this process:

git branch --show-current
git status
npm run build
git add .
git status
git commit -m "Add VS Code workspace documentation"
git push origin develop

Use git add . only after reviewing all listed changes.

For greater control, stage specific files:

git add docs/engineering/development-environment/vscode-workspace.md

VS Code Updates​

Keep Visual Studio Code reasonably current, but avoid updating it immediately before a critical release unless necessary.

After a major VS Code update:

  1. Open the project.
  2. Confirm extensions load correctly.
  3. Verify the integrated terminal.
  4. Run the local build.
  5. Confirm Git branch detection.
  6. Confirm formatting behavior.

Security Practices​

Cloudberrie engineering workspaces must follow these rules:

  • Do not save passwords in source files.
  • Do not commit API keys, tokens, private keys, or service-account credentials.
  • Do not store secrets in Markdown documentation.
  • Do not expose .env files unless they contain approved non-sensitive examples.
  • Do not install untrusted VS Code extensions.
  • Do not approve broad extension permissions without review.
  • Use multi-factor authentication for GitHub and Cloudflare accounts.
  • Store recovery codes in an approved secure password manager.

Daily Workspace Checklist​

Before starting work:

[ ] Open the correct repository root
[ ] Confirm the current folder
[ ] Confirm the Git branch
[ ] Check Git status
[ ] Pull the latest changes
[ ] Confirm Node.js and npm are available

Before committing:

[ ] Review modified and untracked files
[ ] Run the local build or test command
[ ] Review the Git diff
[ ] Confirm no credentials or generated files are included
[ ] Use a clear commit message

Before pushing:

[ ] Confirm the target branch
[ ] Confirm the local build succeeded
[ ] Push to the correct remote branch
[ ] Verify the GitHub commit
[ ] Verify the associated deployment

Troubleshooting​

VS Code opens the wrong folder​

Close the current workspace and reopen the repository root:

cd /Users/cloudberrie/Documents/Cloudberrie/Projects/cb-manual
code .

Git branch is not visible​

Confirm the folder is a Git repository:

git status

If Git reports that the folder is not a repository, verify that the correct folder was opened.

code command is not found​

In VS Code:

Command Palette
→ Shell Command: Install 'code' command in PATH

Then restart the terminal.

Git shows the wrong email​

Run:

git config --global user.email

Correct it with:

git config --global user.email "engineering@cloudberrie.com"

Local files appear unexpectedly modified​

Run:

git status
git diff

Do not discard changes until their source is understood.

VS Code extensions are not working​

Reload the editor:

Command Palette
→ Developer: Reload Window

If the issue continues, disable recently added extensions and test again.

  • Required Software
  • Node.js and npm
  • Git Installation
  • GitHub CLI
  • Git Standards
  • Branch Strategy
  • GitHub Organization
  • Cloudflare Deployment
  • Troubleshooting
Last updated on