Skip to content

!!! tip "Editing these docs" If you change anything under docs/ or this site's structure, validate it builds before opening a PR:

```bash
pip install -r docs/requirements.txt
mkdocs build --strict
```

See also: [Style Guide](style-guide.md), [Governance & Enforcement](governance.md),
[Code of Conduct](code-of-conduct.md).

Contributing to PlainScript

Thank you for your interest in contributing to PlainScript! We welcome contributions from everyone, whether it's code, documentation, bug reports, or feature suggestions.

Code of Conduct

Please read and follow our CODE_OF_CONDUCT.md. We are committed to providing a welcoming and inclusive environment.

Getting Started

Prerequisites

Setup Development Environment

  1. Fork the repository on GitHub
  2. Clone your fork:
git clone https://github.com/YOUR_USERNAME/PlainScript.git
cd PlainScript
  1. Add upstream remote:
git remote add upstream https://github.com/mrhunsaker/PlainScript.git
  1. Install dependencies:
npm install
npm run download:plugins
  1. Verify setup:
npm run build --workspace=custom-ui

Development Workflow

Creating a Feature Branch

# Update main from upstream
git fetch upstream
git checkout main
git reset --hard upstream/main

# Create a feature branch
git checkout -b feature/your-feature-name

Branch naming conventions:

  • feature/short-description — New features
  • fix/short-description — Bug fixes
  • docs/short-description — Documentation
  • refactor/short-description — Code refactoring
  • test/short-description — Test additions

Running the IDE

Start both versions simultaneously:

npm run start

Or individually:

npm run start --workspace=browser-app    # http://localhost:3000
npm run start --workspace=electron-app   # Desktop app

Watch Mode

For development with hot reload:

npm run watch

For specific workspace:

npm run watch --workspace=custom-ui

Areas for Contribution

1. UI/UX Improvements

  • Custom color schemes
  • Keyboard shortcut customization
  • Layout variations
  • Accessibility enhancements

Files to modify: custom-ui/src/frontend/

2. Plugin Integration

  • Add useful VSCode extensions
  • Create custom keybindings
  • Develop Theia-specific plugins

Files to modify: Root package.json (theiaPlugins section)

3. Feature Additions

  • Custom commands and contributions
  • Workspace management improvements
  • Custom editor views

Files to modify: Depends on feature (custom-ui, browser-app, electron-app)

4. Documentation

  • Tutorials and guides
  • API documentation
  • Troubleshooting improvements
  • Examples

Files to modify: README.md, create new .md files as needed

5. Testing & Bug Fixes

  • Cross-platform testing (Windows, macOS, Linux)
  • Bug fixes and compatibility improvements
  • Performance optimization

Files to modify: Varies by issue

Making Changes

1. Create a Feature Branch

git checkout -b feature/my-feature
# or
git checkout -b fix/my-bugfix

2. Make Your Changes

Edit relevant files for your contribution type:

Modifying UI layout:

custom-ui/
├── src/frontend/
│   ├── application-shell.ts
│   ├── navigator-widget-factory.ts
│   ├── commands-contributions.ts
│   └── style/

Modifying plugins:

Root package.json → theiaPlugins section

Modifying preferences:

browser-app/package.json → theia.frontend.config.preferences
electron-app/package.json → theia.frontend.config.preferences

3. Test Your Changes

For custom-ui changes:

npm run build --workspace=custom-ui
npm run bundle --workspace=browser-app
npm run bundle --workspace=electron-app

Test in both platforms:

npm run start

Access browser at http://localhost:3000 and verify Electron app launches.

Run tests (if applicable):

npm test

4. Keep Dependencies Updated

Before submitting, ensure no security vulnerabilities:

npm audit
npm audit fix

5. Commit Your Changes

Use clear, descriptive commit messages:

git commit -am 'Add feature: descriptive title

- Change 1
- Change 2
- Fixes #123'

Commit message format:

  • First line: Short summary (50 chars max)
  • Blank line
  • Detailed explanation if needed
  • Reference issues: Fixes #123, Closes #456

6. Push and Create Pull Request

git push origin feature/my-feature

Then create a PR on GitHub with:

  • Clear title describing the change
  • Description of what and why
  • Screenshots if UI-related
  • Testing steps
  • Any breaking changes noted

Development Guidelines

Code Style

  • Follow existing code patterns in the project
  • Use TypeScript for new code
  • Format with prettier (if configured)
  • Keep functions small and focused

Testing

  • Test changes in both browser and Electron versions
  • Verify plugin loading if plugin-related
  • Check console for errors and warnings
  • Test on different platforms if possible

Documentation

  • Update README.md for user-facing changes
  • Add comments to complex logic
  • Document new configuration options
  • Update this file if process changes

Performance

  • Minimize bundle size impact
  • Avoid unnecessary re-renders (React)
  • Profile before/after changes
  • Consider plugin loading time

Security

  • Don't add credentials or secrets
  • Run npm audit regularly
  • Keep dependencies updated
  • Report security issues privately

Pull Request Guidelines

Before submitting PR:

  • [ ] Changes tested in both browser and Electron
  • [ ] No breaking changes (or clearly documented)
  • [ ] Code follows project style
  • [ ] Dependencies updated if needed
  • [ ] No security issues (npm audit)
  • [ ] Documentation updated

PR Template:

## Description

Brief description of changes

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] UI improvement
- [ ] Documentation
- [ ] Other

## Testing

Steps to verify the change:

1.
2.
3.

## Screenshots (if applicable)

Before/after or relevant UI changes

## Checklist

- [ ] Tested in browser version
- [ ] Tested in Electron version
- [ ] Updated documentation
- [ ] No security issues
- [ ] Build successful

Common Development Tasks

Adding a Plugin

  1. Find extension on Open VSX
  2. Get VSIX URL
  3. Add to package.json:
"publisher.extension-name": "https://open-vsx.org/api/.../file/...vsix"
  1. Run npm run download:plugins
  2. Test: npm run start

Modifying UI Layout

  1. Edit files in custom-ui/src/frontend/
  2. Rebuild: npm run build --workspace=custom-ui
  3. Bundle: npm run bundle --workspace=browser-app && npm run bundle --workspace=electron-app
  4. Test: npm run start

Changing Default Theme

Edit both:

  • browser-app/package.json → theia.frontend.config.preferences
  • electron-app/package.json → theia.frontend.config.preferences

Then restart app.

Creating a New Custom Module

  1. Create directory in custom-ui/src/frontend/
  2. Add TypeScript files with exports
  3. Import in index.ts
  4. Register contribution if needed
  5. Build and test

Reporting Issues

When reporting bugs, include:

Required:

  • OS and Node.js version
  • Steps to reproduce
  • Expected vs actual behavior
  • Error message or screenshot

Optional:

  • Browser/Electron console output
  • Custom configuration if relevant
  • Related plugins or extensions
  • Attempted solutions

Good bug report example:

**Environment**:
- OS: Ubuntu 22.04
- Node: 20.11.0
- npm: 10.5.0

**Steps to reproduce**:
1. Launch ./scripts/customide-browser.sh
2. Open a file
3. Try to close the file

**Expected**: File closes
**Actual**: File doesn't close, console shows error

**Error**:

Error: Cannot read property 'close' of undefined at FileWidget.closeFile (application-shell.ts:123)

**Workaround**: Restart the app

Getting Help

Code of Conduct

  • Be respectful and inclusive
  • No harassment or discrimination
  • Constructive feedback only
  • Report violations to maintainers

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.

Thank you for contributing to Custom IDE!