From 51f4ece842bf35679438f4cbb80e928676649143 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 2 Jan 2025 10:20:15 +0000 Subject: [PATCH 1/3] [Docs] Add Jira integration walkthrough and improve configuration docs Co-Authored-By: tom@getport.io --- .../develop-an-integration.md | 35 ++- .../integration-configuration.md | 13 +- .../jira-walkthrough.md | 269 ++++++++++++++++++ .../docs/framework/advanced-configuration.md | 216 ++++++++++++-- .../docs/framework/features/features.md | 6 +- .../docs/framework/framework.md | 10 +- .../framework/pull-request-best-practices.md | 147 ++++++++++ .../docs/getting-started/getting-started.md | 12 +- docs/framework-guides/docs/ocean-overview.md | 6 +- 9 files changed, 670 insertions(+), 44 deletions(-) create mode 100644 docs/framework-guides/docs/develop-an-integration/jira-walkthrough.md create mode 100644 docs/framework-guides/docs/framework/pull-request-best-practices.md diff --git a/docs/framework-guides/docs/develop-an-integration/develop-an-integration.md b/docs/framework-guides/docs/develop-an-integration/develop-an-integration.md index 3c938f49c6..9d0d49b481 100644 --- a/docs/framework-guides/docs/develop-an-integration/develop-an-integration.md +++ b/docs/framework-guides/docs/develop-an-integration/develop-an-integration.md @@ -19,11 +19,30 @@ To develop and publish an integration you need to complete the following steps: These steps do not follow a specific order. Some steps only become relevant near the end of the integration's development, such as publishing. ::: -1. Scaffold a new integration, as seen in [getting started](../getting-started/getting-started.md#scaffold) -2. Add any required code libraries and the [code and logic](./update-integration-code.md) required for the new integration - 1. Be sure to go over the integration [performance](./performance.md) and [code guidelines](./guidelines.md) to ensure a performant and well written integration -3. Update the [`.port/spec.yml`](./integration-spec-and-default-resources.md#specyaml-file) file with metadata of the integration, including the provided kinds and required parameters -4. Update the [`config.yaml`](./integration-configuration.md) file with configuration and parameters for the integration -5. (Optional) Add default definitions to the [`.port/resources`](./integration-spec-and-default-resources.md#port-folder) directory such as [default blueprints](./integration-spec-and-default-resources.md#blueprintsjson-file) and integration [mapping](./integration-spec-and-default-resources.md#port-app-configyml-file) -6. Create the necessary documentation for the new integration including the README and a changelog -7. [Publish](./publish-an-integration.md) the integration +1. **Initialize Your Integration** + - Scaffold a new integration using the steps in the [getting started guide](../getting-started/getting-started.md#scaffold) + - This creates the basic structure for your integration + +2. **Implement Core Functionality** + - Add required code libraries + - Implement your [integration logic](./update-integration-code.md) + - Follow the [performance guidelines](./performance.md) and [code standards](./guidelines.md) + +3. **Configure Integration Settings** + - Update [`.port/spec.yml`](./integration-spec-and-default-resources.md#specyaml-file) with: + - Integration metadata + - Supported resource kinds + - Required parameters + - Set up [`config.yaml`](./integration-configuration.md) with: + - Configuration parameters + - Default settings + +4. **Add Resources (Optional)** + - In [`.port/resources`](./integration-spec-and-default-resources.md#port-folder) directory: + - Add [default blueprints](./integration-spec-and-default-resources.md#blueprintsjson-file) + - Configure [integration mapping](./integration-spec-and-default-resources.md#port-app-configyml-file) + +5. **Documentation and Release** + - Create comprehensive README + - Maintain a changelog + - [Publish](./publish-an-integration.md) your integration diff --git a/docs/framework-guides/docs/develop-an-integration/integration-configuration.md b/docs/framework-guides/docs/develop-an-integration/integration-configuration.md index fc32467f7f..7cde6bffb3 100644 --- a/docs/framework-guides/docs/develop-an-integration/integration-configuration.md +++ b/docs/framework-guides/docs/develop-an-integration/integration-configuration.md @@ -13,7 +13,10 @@ This section explains the structure of the `config.yaml` file. ## `config.yaml` file -The `config.yaml` file is used to specify the default configuration and parameters for the integration during its deployment phase. +While the `config.yaml` file provides default configuration templates, Ocean primarily uses `.env` files for actual configuration values, especially for sensitive information. This separation ensures security and flexibility: + +- `.env` file: Contains actual configuration values, API keys, and sensitive information +- `config.yaml`: Provides templates and default configurations, using environment variable references When an integration is first started, it registers itself with [Port's REST API](https://api.getport.io/static/index.html#/Integrations/post_v1_integration), using the `https://api.getport.io/v1/integration` route. @@ -48,7 +51,7 @@ Let's go over the different sections and their allowed values: #### `initializePortResources` - Initialize Port resources -This configuration is used to specify whether the integration should initialize its default resources in Port as +This configuration is used to specify whether the integration should initialize its default resources in Port as described in the [integration specification](./integration-spec-and-default-resources.md#default-resources). By default, this feature value is set to `false`. To enable it, set the value to `true`. @@ -121,7 +124,11 @@ eventListener: type: KAFKA ``` -This section is used to specify the type of event listener the integration will use to receive events and resync requests from Port. +This section configures how your integration receives and processes events from Port. The event listener component: +- Handles incoming events from Port +- Manages resync requests +- Controls how and when the integration updates its data +- Provides different modes of operation (webhook, polling, or Kafka-based) diff --git a/docs/framework-guides/docs/develop-an-integration/jira-walkthrough.md b/docs/framework-guides/docs/develop-an-integration/jira-walkthrough.md new file mode 100644 index 0000000000..ca3f51ac67 --- /dev/null +++ b/docs/framework-guides/docs/develop-an-integration/jira-walkthrough.md @@ -0,0 +1,269 @@ +--- +title: Building a Jira Integration +sidebar_label: 🔨 Jira Integration Walkthrough +sidebar_position: 6 +--- + +# 🔨 Building a Jira Integration + +This guide walks you through creating a Jira integration for Port using the Ocean framework. We'll cover each step of the process, from initialization to implementation and testing. + +## Prerequisites + +Before starting, ensure you have: +- Ocean CLI installed +- Python 3.11 or higher +- A Jira instance with API access +- Port account with necessary permissions + +## Step 1: Initialize the Integration + +First, create a new Ocean integration using the CLI: + +```bash showLineNumbers +# Create a new integration +ocean init + +# Follow the prompts: +# 1. Choose a name (e.g., "jira") +# 2. Select integration type: "API" +# 3. Choose Python as the language +``` + +This creates a basic integration structure with necessary files and folders. + +## Step 2: Configure the Integration + +### Update spec.yml + +The `.port/spec.yml` file defines your integration's metadata and requirements: + +```yaml showLineNumbers +# .port/spec.yml +kind: Integration +name: jira +description: Sync Jira issues and projects with Port +icon: jira +vendor: atlassian + +service: + image: ghcr.io/port-labs/port-ocean-jira + secrets: + - name: JIRA_API_TOKEN + required: true + - name: JIRA_USERNAME + required: true + +config: + schema: + type: object + required: + - baseUrl + properties: + baseUrl: + type: string + title: Jira Base URL + description: Your Jira instance URL +``` + +### Configure config.yaml + +Set up your integration configuration: + +```yaml showLineNumbers +# config.yaml +integration: + identifier: my-jira-integration + type: jira + +config: + baseUrl: "{{ from env JIRA_URL }}" + username: "{{ from env JIRA_USERNAME }}" + apiToken: "{{ from env JIRA_API_TOKEN }}" + + # Optional configurations + projectKeys: ["PROJ1", "PROJ2"] + maxResults: 100 + + eventListener: + type: "POLLING" + config: + interval: 300 +``` + +## Step 3: Implement the Integration + +### Create the Main Integration Class + +```python showLineNumbers +from typing import AsyncGenerator +from port_ocean.core.handlers.port_app_config import APIPortAppConfig +from port_ocean.core.integrations.base import BaseIntegration +from port_ocean.context.ocean import ocean +from port_ocean.core.ocean_types import ASYNC_GENERATOR_RESYNC_TYPE, ObjectKind + +class JiraIntegration(BaseIntegration): + """Jira integration implementation.""" + + class AppConfigHandlerClass(APIPortAppConfig): + """Configuration handler for Jira integration.""" + pass + + def __init__(self) -> None: + super().__init__() + self.client = None +``` + +### Implement the Jira Client + +```python showLineNumbers +from dataclasses import dataclass +from aiohttp import ClientSession +from port_ocean.exceptions.core import IntegrationError + +@dataclass +class JiraClient: + """Client for interacting with Jira API.""" + + def __init__(self, base_url: str, username: str, api_token: str) -> None: + self.base_url = base_url.rstrip('/') + self.auth = (username, api_token) + self.session = ClientSession() + + async def get_issues(self, jql: str = '') -> list[dict]: + """Fetch issues from Jira.""" + url = f"{self.base_url}/rest/api/2/search" + params = {'jql': jql} if jql else {} + + async with self.session.get(url, params=params, auth=self.auth) as response: + if response.status != 200: + raise IntegrationError(f"Failed to fetch Jira issues: {response.status}") + data = await response.json() + return data['issues'] +``` + +### Add Resync Methods + +```python showLineNumbers +@ocean.on_resync(ObjectKind.ISSUE) +async def on_resync_issues(self, kind: str) -> ASYNC_GENERATOR_RESYNC_TYPE: + """Resync Jira issues.""" + issues = await self.client.get_issues() + + for issue in issues: + yield { + 'identifier': issue['key'], + 'title': issue['fields']['summary'], + 'blueprint': 'jiraIssue', + 'properties': { + 'status': issue['fields']['status']['name'], + 'type': issue['fields']['issuetype']['name'], + 'priority': issue['fields']['priority']['name'], + 'assignee': issue['fields']['assignee']['displayName'], + 'reporter': issue['fields']['reporter']['displayName'], + 'created': issue['fields']['created'], + 'updated': issue['fields']['updated'] + } + } +``` + +## Step 4: Add Port Resources + +### Create Blueprint Definition + +```yaml showLineNumbers +# .port/resources/blueprints.json +{ + "identifier": "jiraIssue", + "title": "Jira Issue", + "icon": "Jira", + "schema": { + "properties": { + "status": { + "type": "string", + "title": "Status" + }, + "type": { + "type": "string", + "title": "Type" + }, + "priority": { + "type": "string", + "title": "Priority" + }, + "assignee": { + "type": "string", + "title": "Assignee" + }, + "reporter": { + "type": "string", + "title": "Reporter" + }, + "created": { + "type": "string", + "format": "date-time", + "title": "Created At" + }, + "updated": { + "type": "string", + "format": "date-time", + "title": "Updated At" + } + }, + "required": ["status", "type"] + } +} +``` + +## Step 5: Validate and Test + +1. Run lint checks: +```bash showLineNumbers +make lint +``` + +2. Verify configuration: +```bash showLineNumbers +# Set required environment variables +export JIRA_URL=https://your-instance.atlassian.net +export JIRA_USERNAME=your-username +export JIRA_API_TOKEN=your-token + +# Run the integration locally +ocean integration run +``` + +## Security Considerations + +The Ocean framework ensures: +- Secure handling of credentials +- No inbound network connectivity required +- Data processing occurs on your premises +- Automatic PII and secret key scrubbing + +## Next Steps + +After implementing your integration: +1. Test thoroughly with your Jira instance +2. Review security settings +3. Deploy the integration +4. Monitor the integration in Port + +## Troubleshooting + +Common issues and solutions: + +1. Authentication Errors + - Verify API token permissions + - Check username format + - Ensure base URL is correct + +2. Rate Limiting + - Adjust polling interval + - Implement pagination + - Use JQL filters to limit data + +3. Data Sync Issues + - Check event listener configuration + - Verify blueprint mappings + - Review Jira field permissions diff --git a/docs/framework-guides/docs/framework/advanced-configuration.md b/docs/framework-guides/docs/framework/advanced-configuration.md index 1ec175dfb4..4bacfe564d 100644 --- a/docs/framework-guides/docs/framework/advanced-configuration.md +++ b/docs/framework-guides/docs/framework/advanced-configuration.md @@ -4,18 +4,148 @@ sidebar_label: ⚙️ Advanced Configuration sidebar_position: 3 --- -# ⚙️ Advanced configuration -The Ocean framework is based on a Python HTTP client called [HTTPX](https://www.python-httpx.org/). The HTTPX client provides out-of-the-box configuration capabilites, which allows configuring the client to work with: +# ⚙️ Advanced Configuration -- Self-signed certificates. -- Proxies. +The Ocean framework provides extensive configuration capabilities through environment variables, YAML files, and configuration providers. This flexibility allows you to customize how Ocean operates in different environments. -These configurations are passed to the client using environment varaibles. +## Overview + +The framework supports several configuration methods: +- Environment variables with the `OCEAN__` prefix +- YAML configuration files (`config.yaml`) +- Environment files (`.env`) +- Configuration providers for value interpolation +- Sensitive field handling + +These configurations enable Ocean to work seamlessly in various enterprise environments while maintaining security and flexibility. + +## Environment Variable Configuration + +### Environment Variable Prefix + +Ocean uses the `OCEAN__` prefix for all its environment variables. For nested configurations, use double underscores (`__`) as delimiters. + +Example: +```bash showLineNumbers +OCEAN__INTEGRATION__IDENTIFIER=my-integration +OCEAN__INTEGRATION__TYPE=jira +OCEAN__CONFIG__API_TOKEN=secret-token +``` + +### Environment File Configuration (Recommended) + +Ocean uses `.env` files as the primary and recommended method for configuration. The framework automatically loads environment variables from a `.env` file in your project directory, providing a secure and convenient way to manage configuration: + +```bash showLineNumbers +# .env file - Primary configuration method +OCEAN__LOG_LEVEL=DEBUG +OCEAN__INTEGRATION__IDENTIFIER=my-integration +OCEAN__PORT__CLIENT_ID=your-client-id +OCEAN__PORT__CLIENT_SECRET=your-client-secret +OCEAN__CONFIG__API_TOKEN=your-api-token + +# Integration-specific configuration +OCEAN__CONFIG__BASE_URL=https://your-instance.atlassian.net +OCEAN__CONFIG__USERNAME=your-username +``` + +Benefits of using .env files: +- Secure storage of sensitive information +- Easy environment-specific configuration +- Prevents accidental commits of secrets +- Supports development and production environments +- Automatic loading by the Ocean framework + +## Configuration Providers + +Ocean supports value interpolation using configuration providers. This allows you to reference environment variables in your YAML configuration: + +```yaml showLineNumbers +integration: + identifier: "{{ from env INTEGRATION_ID }}" + type: "jira" +config: + apiToken: "{{ from env JIRA_API_TOKEN }}" +``` + +The `from env` provider loads values from environment variables, making it easy to keep sensitive information out of your configuration files. + +## Common Environment Variables + +Ocean provides several built-in environment variables to control its behavior: + +### Core Variables + +- `OCEAN__LOG_LEVEL`: Controls logging verbosity (DEBUG, INFO, WARNING, ERROR) +- `OCEAN__INTEGRATION__IDENTIFIER`: Unique identifier for your integration +- `OCEAN__INTEGRATION__TYPE`: Type of integration (e.g., jira, gitlab) +- `OCEAN__PORT__CLIENT_ID`: Port platform client ID +- `OCEAN__PORT__CLIENT_SECRET`: Port platform client secret +- `OCEAN__PORT__BASE_URL`: Port API base URL + +Example: +```bash showLineNumbers +OCEAN__LOG_LEVEL=DEBUG +OCEAN__INTEGRATION__IDENTIFIER=my-jira-integration +OCEAN__PORT__BASE_URL=https://api.getport.io +``` + +### Integration-Specific Configuration + +Each integration type can define its own configuration variables. Here's an example for the Jira integration: + +```yaml showLineNumbers +# config.yaml +integration: + identifier: "{{ from env INTEGRATION_ID }}" + type: "jira" + +config: + # Jira-specific configuration + baseUrl: "{{ from env JIRA_URL }}" + username: "{{ from env JIRA_USERNAME }}" + apiToken: "{{ from env JIRA_API_TOKEN }}" + + # Optional configurations + projectKeys: ["PROJ1", "PROJ2"] + maxResults: 100 + + # Event listener configuration + eventListener: + type: "POLLING" + config: + interval: 300 # Polling interval in seconds +``` + +Environment variables for this configuration: +```bash showLineNumbers +OCEAN__CONFIG__BASE_URL=https://your-instance.atlassian.net +OCEAN__CONFIG__USERNAME=your-username +OCEAN__CONFIG__API_TOKEN=your-api-token +``` + +### Advanced Integration Settings + +Additional settings that can be configured: + +- `OCEAN__CONFIG__MAX_RETRIES`: Maximum number of API retry attempts +- `OCEAN__CONFIG__TIMEOUT`: API request timeout in seconds +- `OCEAN__CONFIG__BATCH_SIZE`: Number of items to process in each batch +- `OCEAN__EVENT_LISTENER__TYPE`: Event listener type (POLLING, KAFKA, WEBHOOK) + +These settings can be configured either through environment variables or in the `config.yaml` file. ## Proxy configuration -### `HTTP_PROXY`, `HTTPS_PROXY` & `ALL_PROXY` -`HTTP_PROXY`, `HTTPS_PROXY`, and `ALL_PROXY` are environment variables used to specify a proxy server for handling HTTP, HTTPS, or all types of requests, respectively. The values assigned to these settings should be the URL of the proxy server. +### Proxy Environment Variables + +#### `HTTP_PROXY`, `HTTPS_PROXY` & `ALL_PROXY` +These environment variables configure proxy servers for different types of requests: +- `HTTP_PROXY`: Handles HTTP requests +- `HTTPS_PROXY`: Handles HTTPS requests +- `ALL_PROXY`: Handles all types of requests + +Each variable should be set to the URL of the corresponding proxy server. For example: ```bash showLineNumbers @@ -24,9 +154,11 @@ HTTPS_PROXY=http://my-proxy.com:2222 ALL_PROXY=http://my-proxy.com:3333 ``` -### `NO_PROXY` - -`NO_PROXY` allows blacklisting certain addresses from being handled through a proxy. This vairable accepts a comma-seperated list of hostnames or urls. +#### `NO_PROXY` +This environment variable allows you to bypass the proxy for specific addresses: +- Accepts a comma-separated list of hostnames or URLs +- Useful for accessing internal services directly +- Common for local development environments For example: ```bash showLineNumbers @@ -35,34 +167,72 @@ NO_PROXY=http://127.0.0.1,google.com For more information take a look at the HTTPX [proxy configuration documentation](https://www.python-httpx.org/environment_variables/#proxies). -## SSL Environment Configuration +## SSL/TLS Configuration -`SSLKEYLOGFILE`, `SSL_CERT_DIR`, and `SSL_CERT_FILE` are environment variables that control various aspects of SSL (Secure Sockets Layer) communication. +The Ocean framework provides comprehensive SSL/TLS configuration options through environment variables. These settings allow you to customize how the framework handles secure connections, certificates, and encryption. -### `SSLKEYLOGFILE` -This variable specifies the file path where SSL/TLS key information will be logged. This is particularly useful for debugging encrypted SSL/TLS connections, as it allows network analyzers like Wireshark to decrypt and inspect the traffic. +### SSL Environment Variables -For example: +#### `SSLKEYLOGFILE` +This variable enables SSL/TLS debugging capabilities: +- Specifies where to log SSL/TLS key information +- Enables network analysis tools like Wireshark to inspect encrypted traffic +- Useful for troubleshooting SSL/TLS connection issues + +Example: ```bash showLineNumbers SSLKEYLOGFILE=/path/to/sslkeylogfile.txt ``` -### `SSL_CERT_DIR` -This variable sets the directory path where the program looks for SSL/TLS certificates. Instead of a single file, `SSL_CERT_DIR` points to a directory that contains multiple certificate files. This is useful when you have a collection of trusted CA (Certificate Authority) certificates split into different files. +#### `SSL_CERT_DIR` +This variable configures certificate directory settings: +- Points to a directory containing multiple certificate files +- Useful for managing multiple trusted CA certificates +- Common in enterprise environments with custom certificate authorities -For example: +Example: ```bash showLineNumbers SSL_CERT_DIR=/etc/ssl/certs ``` -### `SSL_CERT_FILE` -This variable points to a single file that contains a bundle of concatenated CA certificates, which are used to validate the SSL/TLS connections. The file should contain a series of trusted certificates in PEM format. This is useful when your application needs to validate server certificates against a specific set of CAs. +#### `SSL_CERT_FILE` +This variable specifies a certificate bundle file: +- Points to a single file containing multiple CA certificates +- Certificates must be in PEM format +- Used when validating server certificates against specific CAs -For example: +Example: ```bash showLineNumbers SSL_CERT_FILE=/path/to/cacert.pem ``` -These variables provide fine-grained control over SSL/TLS configurations in environments where default settings are not sufficient or need customization for specific requirements. +### Use Cases + +These SSL/TLS configurations are particularly useful in: +- Enterprise environments with custom certificate authorities +- Development environments requiring SSL/TLS debugging +- Environments with specific security requirements +- Scenarios involving self-signed certificates + +For detailed information about SSL configuration options, refer to the HTTPX [SSL configuration documentation](https://www.python-httpx.org/environment_variables/#sslkeylogfile). + +## Sensitive Field Handling + +Ocean provides built-in support for handling sensitive information through the `sensitive` field attribute. Fields marked as sensitive are automatically handled with extra care: + +```python showLineNumbers +from pydantic import BaseModel +from port_ocean import BaseOceanModel + +class IntegrationConfig(BaseOceanModel): + api_token: str = Field(..., sensitive=True) + base_url: str + +``` + +Sensitive fields are: +- Masked in logs and error messages +- Protected from accidental exposure +- Handled securely during serialization -For more information take a look at the HTTPX [SSL configuration documentation](https://www.python-httpx.org/environment_variables/#sslkeylogfile). +This ensures that sensitive information like API tokens and credentials remains secure throughout the integration's lifecycle. diff --git a/docs/framework-guides/docs/framework/features/features.md b/docs/framework-guides/docs/framework/features/features.md index 7a30d7d954..755e2c4f97 100644 --- a/docs/framework-guides/docs/framework/features/features.md +++ b/docs/framework-guides/docs/framework/features/features.md @@ -8,8 +8,10 @@ import DocCardList from '@theme/DocCardList'; # ⭐️ Features -The Ocean framework was made to abstract, speed up and streamline the development of integrations for Port. As such, it comes with a variety of abstractions and features that make development for Port and interaction with Port's API simple an straight forward. +The Ocean framework is designed to abstract, speed up, and streamline the development of integrations for Port. It provides a comprehensive set of abstractions and features that make development and interaction with Port's API simple and straightforward. -See the variety of available features and abstractions below: +## Available Features and Abstractions + +Below you'll find the core features that Ocean provides to help you build robust integrations: diff --git a/docs/framework-guides/docs/framework/framework.md b/docs/framework-guides/docs/framework/framework.md index c3ef25a373..7580acd368 100644 --- a/docs/framework-guides/docs/framework/framework.md +++ b/docs/framework-guides/docs/framework/framework.md @@ -1,6 +1,10 @@ -# Framework +# Ocean Framework This section outlines the different features and components provided by the Ocean framework to make the development of new integrations for Port easier and more efficient. -- To learn about features and abstractions provided by the Ocean framework, refer to the [features](./features/features.md) section. -- To learn about Ocean's CLI interface, refer to the [CLI](./cli/cli.md) section. +## Key Components + +- **Features and Abstractions**: Learn about the core capabilities and abstractions provided by the Ocean framework in the [features documentation](./features/features.md). +- **Command Line Interface**: Understand how to use Ocean's CLI tools by referring to the [CLI documentation](./cli/cli.md). + +Each component is designed to streamline the integration development process and provide a consistent experience across different types of integrations. diff --git a/docs/framework-guides/docs/framework/pull-request-best-practices.md b/docs/framework-guides/docs/framework/pull-request-best-practices.md new file mode 100644 index 0000000000..8821884574 --- /dev/null +++ b/docs/framework-guides/docs/framework/pull-request-best-practices.md @@ -0,0 +1,147 @@ +--- +title: Pull Request Best Practices +sidebar_label: 📝 Pull Request Best Practices +sidebar_position: 4 +--- + +# 📝 Pull Request Best Practices + +This guide outlines the best practices for creating and managing pull requests in the Ocean framework repository. Following these guidelines helps maintain code quality and ensures smooth collaboration. + +## Pull Request Title Format + +Pull request titles must follow this pattern: +``` +[Category][Optional Subcategory] Description +``` + +Where: +- `Category` must be one of: + - `Integration` - Changes to integration code + - `Core` - Changes to Ocean framework core + - `Docs` - Documentation changes + - `CI` - CI/CD pipeline changes + - `Infra` - Infrastructure changes +- `Optional Subcategory` - Additional context (e.g., `[AWS]`, `[Jira]`) +- `Description` - Clear, concise description of changes + +Examples: +- `[Integration][AWS] Add support for ECS tags` +- `[Core] Improve error handling in HTTP client` +- `[Docs] Add Jira integration walkthrough` + +## Branch Naming Convention + +Branch names should be descriptive and follow this format: +``` +feature/short-description +bugfix/issue-description +docs/documentation-change +``` + +## Pull Request Description + +Your PR description should include: + +1. **Overview** + - Brief description of changes + - Motivation for changes + - Related issues or discussions + +2. **Changes Made** + - List of significant changes + - Any breaking changes + - New features or improvements + +3. **Testing** + - How changes were tested + - Test coverage information + - Manual testing steps if applicable + +4. **Additional Context** + - Screenshots (if applicable) + - Performance implications + - Security considerations + +## Code Review Process + +### As a PR Author + +1. **Before Creating PR** + - Run linting checks (`make lint`) + - Ensure all tests pass + - Review your own changes + - Update documentation if needed + +2. **After Creating PR** + - Respond to reviewer comments promptly + - Make requested changes + - Keep PR updated with base branch + +3. **Before Merging** + - Ensure CI checks pass + - Get required approvals + - Resolve all conversations + +### As a Reviewer + +1. **Review Checklist** + - Code follows style guidelines + - Tests are adequate + - Documentation is updated + - Changes meet requirements + +2. **Providing Feedback** + - Be constructive and specific + - Explain reasoning for changes + - Distinguish between required and optional changes + +## Best Practices + +1. **Keep PRs Focused** + - One feature/fix per PR + - Limit scope of changes + - Split large changes into smaller PRs + +2. **Commit Messages** + - Use clear, descriptive messages + - Reference issues when applicable + - Follow conventional commits format + +3. **Documentation** + - Update relevant docs + - Include code comments + - Add examples for new features + +4. **Testing** + - Add/update tests + - Test edge cases + - Include integration tests + +5. **Security** + - No sensitive data in code + - Follow security best practices + - Review access controls + +## Common Issues to Avoid + +1. **Code Quality** + - Mixing formatting with content changes + - Large, unfocused PRs + - Missing tests or documentation + +2. **Process** + - Force pushing to branches + - Merging without reviews + - Ignoring CI failures + +3. **Communication** + - Unclear PR descriptions + - Delayed responses to feedback + - Missing context or motivation + +## Additional Resources + +- [Ocean Framework Documentation](../framework.md) +- [Contributing Guidelines](../../contributing.md) +- [Code Style Guide](../../code-style-guide.md) diff --git a/docs/framework-guides/docs/getting-started/getting-started.md b/docs/framework-guides/docs/getting-started/getting-started.md index d84960274b..2370a81f63 100644 --- a/docs/framework-guides/docs/getting-started/getting-started.md +++ b/docs/framework-guides/docs/getting-started/getting-started.md @@ -10,7 +10,15 @@ In this quickstart guide, you'll learn how to **install** the Ocean CLI, **scaff ## Requirements -Python 3.11 +### Python Environment +- Python 3.11 or higher +- A virtual environment (recommended) +- pip package manager + +### Development Tools +- Git for version control +- Basic understanding of Python development +- Text editor or IDE of your choice ## Installation @@ -60,7 +68,7 @@ $ y Here are your next steps: ⚓️ Install necessary packages: Run cd ./my_integration && make install && . .venv/bin/activate to install all required packages for your project. -⚓️ Copy example env file: Run cp .env.example .env and update your integration's configuration in the .env file. +⚓️ Configure your integration: Run cp .env.example .env and update your integration's configuration in the .env file. Ocean uses .env as its primary configuration method for secure and easy setup. ⚓️ Set sail with Ocean: Run ocean sail to run the project using Ocean. ⚓️ Smooth sailing with Make: Alternatively, you can run make run ./my_integration to launch your project using Make. ``` diff --git a/docs/framework-guides/docs/ocean-overview.md b/docs/framework-guides/docs/ocean-overview.md index bff2222066..1bd330667b 100644 --- a/docs/framework-guides/docs/ocean-overview.md +++ b/docs/framework-guides/docs/ocean-overview.md @@ -13,8 +13,8 @@ import OceanRealTimeArchSvg from '../static/img/RealTimeUpdatesArchitecture.svg' ![Thumbnail](https://raw.githubusercontent.com/port-labs/ocean/main/assets/Thumbnail.png)

- - Lint + + Lint Package version @@ -54,7 +54,7 @@ Ocean is made up of two distinct pieces: - Ocean CLI - used to create boilerplates for new Ocean integrations, and to aid in their development. - The Ocean Framework - provides common functionalities and interfaces to make the development of new Port integrations faster and easier. -The following section provides a deep dive into the Ocean framework, To learn more about the Ocean CLI, refer to the [CLI](./framework/cli/cli.md) docs +The following section provides a deep dive into the Ocean framework. To learn more about the Ocean CLI, refer to the [CLI documentation](./framework/cli/cli.md) ### The Ocean framework From ce4bf9904d35cea02a94a6e034d10d85b5ce0c59 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 2 Jan 2025 10:29:44 +0000 Subject: [PATCH 2/3] [Docs] Fix documentation links in PR best practices guide Co-Authored-By: tom@getport.io --- .../docs/framework/pull-request-best-practices.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/framework-guides/docs/framework/pull-request-best-practices.md b/docs/framework-guides/docs/framework/pull-request-best-practices.md index 8821884574..1a12fffca7 100644 --- a/docs/framework-guides/docs/framework/pull-request-best-practices.md +++ b/docs/framework-guides/docs/framework/pull-request-best-practices.md @@ -142,6 +142,6 @@ Your PR description should include: ## Additional Resources -- [Ocean Framework Documentation](../framework.md) -- [Contributing Guidelines](../../contributing.md) -- [Code Style Guide](../../code-style-guide.md) +- [Ocean Framework Documentation](./framework.md) +- [Contributing Guidelines](../contributing.md) +- [Code Style Guide](../code-style-guide.md) From dffe5377dd7a8d50ab3b3dc33048e3be924fa0d9 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 2 Jan 2025 10:46:51 +0000 Subject: [PATCH 3/3] [Docs] Fix documentation links in PR best practices guide Co-Authored-By: tom@getport.io --- .../docs/framework/pull-request-best-practices.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/framework-guides/docs/framework/pull-request-best-practices.md b/docs/framework-guides/docs/framework/pull-request-best-practices.md index 1a12fffca7..a9b75f3c7b 100644 --- a/docs/framework-guides/docs/framework/pull-request-best-practices.md +++ b/docs/framework-guides/docs/framework/pull-request-best-practices.md @@ -143,5 +143,4 @@ Your PR description should include: ## Additional Resources - [Ocean Framework Documentation](./framework.md) -- [Contributing Guidelines](../contributing.md) -- [Code Style Guide](../code-style-guide.md) +- [Contributing Guidelines](../contributing/contributing.md)