Skip to main content

OIBus Developer Handbook

Welcome to the OIBus developer community! This guide will help you get started with contributing to OIBus.

🚀 Getting Started​

Prerequisites​

Before you begin, ensure you have the following installed:

  • Git
  • Node.js (check .nvmrc for required version)
  • nvm (recommended for Node.js version management)
  • SQLite browser or DBeaver (for database inspection)
  • Your preferred IDE (VS Code, IntelliJ, etc.)
ToolPurposeInstallation
Node.jsJavaScript runtimeDownload
nvmNode version managerInstallation guide
DBeaverDatabase managementDownload
VS CodeCode editorDownload
Angular CLIFrontend developmentInstalled via npm

📥 Setting Up Your Development Environment​

1. Get the Source Code​

Choose one of these options:

Option A: For Contributors (Recommended)

# Fork the repository on GitHub first
git clone git@github.com:<your-username>/OIBus.git
cd OIBus
git remote add upstream git@github.com:OptimistikSAS/OIBus.git

Option B: For Evaluation Only

git clone git@github.com:OptimistikSAS/OIBus.git
cd OIBus

2. Install Dependencies​

# Install Node.js version specified in .nvmrc
nvm install
nvm use

3. Set Up the Backend​

cd backend
npm install
npm start  # Starts on http://localhost:2223

4. Set Up the Frontend​

cd frontend
npm install
npm start  # Builds and watches for changes
Frontend Note

The frontend is served by the backend. While npm start watches for changes, you'll need to manually refresh your browser to see updates.

5. Set Up Documentation​

cd documentation
npm install
npm start  # Starts on http://localhost:3000

6. Verify Your Setup​

🛠 Development Workflow​

Project Structure​

OIBus/
├── backend/          # Backend server (Node.js)
├── frontend/         # Frontend application (Angular)
├── documentation/    # Project documentation (Docusaurus)
└── data-folder/      # Runtime data (created automatically)

Quick Test Setup​

To verify everything works:

  1. Create a FolderScanner South connector (reads files from a directory)
  2. Create a Console North connector (outputs to console)
  3. Configure them to work together

🔧 Development Guidelines​

Branch Naming​

<type>/<descriptive-name>#<issue-number>

Examples:

  • feature/add-new-connector#1234
  • fix/folder-scanner-bug#5678
  • docs/update-readme#9101

Commit Messages​

Follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Common types: feat, fix, docs, style, refactor, test, chore

Testing Requirements​

All changes must include tests:

Run tests with:

# Backend tests
cd backend
npm test

# Frontend tests
cd frontend
npm test

# Linting
npm run lint

📤 Submitting Contributions​

Before You Start​

  1. Check existing issues for similar work
  2. Create a feature issue if adding new functionality
  3. Discuss your approach with maintainers before coding

Pull Request Process​

  1. Create a branch from main with proper naming
  2. Make your changes and commit with clear messages
  3. Push to your fork
  4. Create a Pull Request to OptimistikSAS/OIBus:main
  5. Ensure all tests pass
  6. Wait for code review and address feedback

Pull Request Checklist​

  • Code follows project style guidelines
  • All tests pass
  • Documentation updated (if applicable)
  • Changes are backward compatible
  • New features include tests

🤝 Community Guidelines​

How to Contribute​

  1. Start small: Fix typos, improve docs, or tackle "good first issue" labels
  2. Ask questions: Use GitHub discussions or issues
  3. Be patient: We'll review your PR as soon as possible
  4. Stay engaged: Be responsive to feedback

Code of Conduct​

We follow a Code of Conduct to ensure a welcoming community.

📚 Learning Resources​

Technologies Used​

AreaTechnologyLearning Resources
BackendNode.jsNode.js Docs
FrontendAngularAngular Docs
DocumentationDocusaurusDocusaurus Docs
TestingJest/JasmineJest Docs, Jasmine Docs

🎯 First Contributions​

Looking for your first contribution? Check out:

Ready to contribute? We're excited to have you! 🎉