Contribuir
Otros idiomas
Aprenda como contribuir al proyecto Symbiont, desde reportar problemas hasta enviar cambios de codigo.
Tabla de contenidos
- Descripcion General
- Primeros Pasos
- Fork the repository on GitHub, then clone your fork
- Add upstream remote
- Run all tests
- Run specific test suites
- Run with coverage
Descripcion General
Symbiont da la bienvenida a contribuciones de la comunidad. Ya sea que estes corrigiendo errores, agregando funcionalidades, mejorando la documentacion o proporcionando retroalimentacion, tus contribuciones ayudan a hacer Symbiont mejor para todos.
Formas de Contribuir
- Reportes de Errores: Ayuda a identificar y resolver problemas
- Solicitudes de Funcionalidades: Sugiere nuevas capacidades y mejoras
- Documentacion: Mejora guias, ejemplos y documentacion de API
- Contribuciones de Codigo: Corrige errores e implementa nuevas funcionalidades
- Seguridad: Reporta vulnerabilidades de seguridad de forma responsable
- Pruebas: Agrega casos de prueba y mejora la cobertura de pruebas
Primeros Pasos
Requisitos Previos
Antes de contribuir, asegurese de tener:
- Rust 1.88+ con cargo
- Git para control de versiones
- Docker para pruebas y desarrollo
- Conocimiento basico de Rust, principios de seguridad y sistemas de IA
Configuracion del Entorno de Desarrollo
- Hacer Fork y Clonar el Repositorio
```bash
Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/symbiont.git cd symbiont
Add upstream remote
git remote add upstream https://github.com/thirdkeyai/symbiont.git
2. **Configurar el Entorno de Desarrollo**
```bash
# Install Rust dependencies
rustup update
rustup component add rustfmt clippy
# Install pre-commit hooks
cargo install pre-commit
pre-commit install
# Build the project
cargo build
Run specific test suites
cargo test –package symbiont-dsl cargo test –package symbiont-runtime
Run with coverage
cargo tarpaulin –out html
4. **Iniciar Servicios de Desarrollo**
```bash
# Start required services with Docker Compose
docker-compose up -d redis postgres
# Verify services are running
cargo run --example basic_agent
Directrices de Desarrollo
Estandares de Codigo
Estilo de Codigo Rust:
- Usar
rustfmtpara formateo consistente - Seguir las convenciones de nomenclatura de Rust
- Escribir codigo Rust idiomatico
- Incluir documentacion completa
- Agregar pruebas unitarias para toda funcionalidad nueva
Requisitos de Seguridad:
- Todo el codigo relacionado con seguridad debe ser revisado
- Las operaciones criptograficas deben usar bibliotecas aprobadas
- Se requiere validacion de entrada para todas las APIs publicas
- Las pruebas de seguridad deben acompanar las funcionalidades de seguridad
Directrices de Rendimiento:
- Hacer benchmarks del codigo critico para el rendimiento
- Evitar asignaciones innecesarias en rutas criticas
- Usar
async/awaitpara operaciones de E/S - Perfilar el uso de memoria para funcionalidades intensivas en recursos
Organizacion del Codigo
symbiont/
├── dsl/ # DSL parser and grammar
│ ├── src/
│ ├── tests/
│ └── tree-sitter-symbiont/
├── runtime/ # Core runtime system
│ ├── src/
│ │ ├── api/ # HTTP API (optional)
│ │ ├── context/ # Context management
│ │ ├── integrations/ # External integrations
│ │ ├── rag/ # RAG engine
│ │ ├── scheduler/ # Task scheduling
│ │ └── types/ # Core type definitions
│ ├── examples/ # Usage examples
│ ├── tests/ # Integration tests
│ └── docs/ # Technical documentation
├── enterprise/ # Enterprise features
│ └── src/
└── docs/ # Community documentation
Directrices de Commits
Formato de Mensajes de Commit:
<type>(<scope>): <description>
[optional body]
[optional footer]
Tipos:
feat: Nueva funcionalidadfix: Correccion de errordocs: Cambios en documentacionstyle: Cambios de estilo de codigo (formateo, etc.)refactor: Refactorizacion de codigotest: Agregar o actualizar pruebaschore: Tareas de mantenimiento
Ejemplos:
feat(runtime): add multi-tier sandbox support
Implements Docker, gVisor, and Firecracker isolation tiers with
automatic risk assessment and tier selection.
Closes #123
fix(dsl): resolve parser error with nested policy blocks
The parser was incorrectly handling nested policy definitions,
causing syntax errors for complex security configurations.
docs(security): update cryptographic implementation details
Add detailed documentation for Ed25519 signature implementation
and key management procedures.
Tipos de Contribuciones
Reportes de Errores
Al reportar errores, por favor incluya:
Informacion Requerida:
- Version de Symbiont y plataforma
- Pasos minimos de reproduccion
- Comportamiento esperado vs. real
- Mensajes de error y registros
- Detalles del entorno
Plantilla de Reporte de Errores:
## Bug Description
Brief description of the issue
## Steps to Reproduce
1. Step one
2. Step two
3. Step three
## Expected Behavior
What should happen
## Actual Behavior
What actually happens
## Environment
- OS: [e.g., Ubuntu 22.04]
- Rust version: [e.g., 1.88.0]
- Symbiont version: [e.g., 1.0.0]
- Docker version: [if applicable]
## Additional Context
Any other relevant information
Solicitudes de Funcionalidades
Proceso de Solicitud de Funcionalidades:
- Verificar issues existentes para solicitudes similares
- Crear un issue detallado de solicitud de funcionalidad
- Participar en la discusion y el diseno
- Implementar la funcionalidad siguiendo las directrices
Plantilla de Solicitud de Funcionalidad:
## Feature Description
Clear description of the proposed feature
## Motivation
Why is this feature needed? What problem does it solve?
## Detailed Design
How should this feature work? Include examples if possible.
## Alternatives Considered
What other solutions were considered?
## Implementation Notes
Any technical considerations or constraints
Contribuciones de Codigo
Proceso de Pull Request:
- Crear Rama de Funcionalidad
git checkout -b feature/descriptive-name - Implementar Cambios
- Escribir codigo siguiendo las guias de estilo
- Agregar pruebas completas
- Actualizar la documentacion segun sea necesario
- Asegurarse de que todas las pruebas pasen
- Hacer Commit de los Cambios
git add . git commit -m "feat(component): descriptive commit message" - Push y Crear PR
git push origin feature/descriptive-name # Create pull request on GitHub
Requisitos del Pull Request:
- Todas las pruebas pasan
- El codigo sigue las guias de estilo
- La documentacion esta actualizada
- Se han considerado las implicaciones de seguridad
- Se ha evaluado el impacto en el rendimiento
- Los cambios que rompen compatibilidad estan documentados
Contribuciones de Documentacion
Tipos de Documentacion:
- Guias de Usuario: Ayudan a los usuarios a comprender y usar las funcionalidades
- Documentacion de API: Referencia tecnica para desarrolladores
- Ejemplos: Ejemplos de codigo funcional y tutoriales
- Documentacion de Arquitectura: Diseno del sistema y detalles de implementacion
Estandares de Documentacion:
- Escribir prosa clara y concisa
- Incluir ejemplos de codigo funcional
- Usar formato y estilo consistentes
- Probar todos los ejemplos de codigo
- Actualizar documentacion relacionada
Estructura de la Documentacion:
---
layout: default
title: Page Title
nav_order: N
description: "Brief page description"
---
# Page Title
{: .no_toc }
Brief introduction paragraph.
{: .fs-6 .fw-300 }
## Table of contents
{: .no_toc .text-delta }
1. TOC
{:toc}
---
## Content sections...
Directrices de Pruebas
Tipos de Pruebas
Pruebas Unitarias:
- Probar funciones y modulos individuales
- Simular dependencias externas
- Ejecucion rapida (<1s por prueba)
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_policy_evaluation() {
let policy = Policy::new("test_policy", PolicyRules::default());
let context = PolicyContext::new();
let result = policy.evaluate(&context);
assert_eq!(result, PolicyDecision::Allow);
}
}
Pruebas de Integracion:
- Probar interacciones entre componentes
- Usar dependencias reales cuando sea posible
- Tiempo de ejecucion moderado (<10s por prueba)
#[tokio::test]
async fn test_agent_lifecycle() {
let runtime = test_runtime().await;
let agent_config = AgentConfig::default();
let agent_id = runtime.create_agent(agent_config).await.unwrap();
let status = runtime.get_agent_status(agent_id).await.unwrap();
assert_eq!(status, AgentStatus::Ready);
}
Pruebas de Seguridad:
- Probar controles y politicas de seguridad
- Verificar operaciones criptograficas
- Probar escenarios de ataque
#[tokio::test]
async fn test_sandbox_isolation() {
let sandbox = create_test_sandbox(SecurityTier::Tier2).await;
// Attempt to access restricted resource
let result = sandbox.execute_malicious_code().await;
// Should be blocked by security controls
assert!(result.is_err());
assert_eq!(result.unwrap_err(), SandboxError::AccessDenied);
}
Datos de Prueba
Fixtures de Prueba:
- Usar datos de prueba consistentes entre pruebas
- Evitar valores codificados de forma fija cuando sea posible
- Limpiar datos de prueba despues de la ejecucion
pub fn create_test_agent_config() -> AgentConfig {
AgentConfig {
id: AgentId::new(),
name: "test_agent".to_string(),
security_tier: SecurityTier::Tier1,
memory_limit: 512 * 1024 * 1024, // 512MB
capabilities: vec!["test".to_string()],
policies: vec![],
metadata: HashMap::new(),
}
}
Consideraciones de Seguridad
Proceso de Revision de Seguridad
Cambios Sensibles a la Seguridad: Todos los cambios que afecten la seguridad deben pasar por una revision adicional:
- Implementaciones criptograficas
- Autenticacion y autorizacion
- Validacion y sanitizacion de entrada
- Mecanismos de sandbox y aislamiento
- Sistemas de auditoria y registro
Lista de Verificacion de Revision de Seguridad:
- Modelo de amenazas actualizado si es necesario
- Pruebas de seguridad agregadas
- Bibliotecas criptograficas aprobadas
- Validacion de entrada completa
- El manejo de errores no filtra informacion
- Registro de auditoria completo
Reporte de Vulnerabilidades
Divulgacion Responsable: Si descubre una vulnerabilidad de seguridad:
- NO cree un issue publico
- Envie un correo a security@thirdkey.ai con los detalles
- Proporcione pasos de reproduccion si es posible
- Permita tiempo para investigacion y correccion
- Coordine el cronograma de divulgacion
Plantilla de Reporte de Seguridad:
Subject: Security Vulnerability in Symbiont
Component: [affected component]
Severity: [critical/high/medium/low]
Description: [detailed description]
Reproduction: [steps to reproduce]
Impact: [potential impact]
Suggested Fix: [if applicable]
Proceso de Revision
Directrices de Revision de Codigo
Para Autores:
- Mantener los cambios enfocados y atomicos
- Escribir mensajes de commit claros
- Agregar pruebas para funcionalidad nueva
- Actualizar la documentacion segun sea necesario
- Responder prontamente a la retroalimentacion de revision
Para Revisores:
- Enfocarse en la correccion del codigo y la seguridad
- Verificar el cumplimiento de las directrices
- Verificar que la cobertura de pruebas sea adecuada
- Asegurarse de que la documentacion este actualizada
- Ser constructivo y util
Criterios de Revision:
- Correccion: El codigo funciona como se espera?
- Seguridad: Hay implicaciones de seguridad?
- Rendimiento: El rendimiento es aceptable?
- Mantenibilidad: El codigo es legible y mantenible?
- Pruebas: Las pruebas son completas y confiables?
Requisitos de Merge
Todos los PRs Deben:
- Pasar todas las pruebas automatizadas
- Tener al menos una revision aprobatoria
- Incluir documentacion actualizada
- Seguir los estandares de codificacion
- Incluir pruebas apropiadas
PRs Sensibles a la Seguridad Deben:
- Tener revision del equipo de seguridad
- Incluir pruebas de seguridad
- Actualizar el modelo de amenazas si es necesario
- Tener documentacion de pista de auditoria
Directrices de la Comunidad
Codigo de Conducta
Estamos comprometidos a proporcionar un entorno acogedor e inclusivo para todos los contribuyentes. Por favor lea y siga nuestro Codigo de Conducta.
Principios Clave:
- Respeto: Tratar a todos los miembros de la comunidad con respeto
- Inclusion: Dar la bienvenida a perspectivas y origenes diversos
- Colaboracion: Trabajar juntos de manera constructiva
- Aprendizaje: Apoyar el aprendizaje y el crecimiento
- Calidad: Mantener altos estandares para el codigo y el comportamiento
Comunicacion
Canales:
- GitHub Issues: Reportes de errores y solicitudes de funcionalidades
- GitHub Discussions: Preguntas generales e ideas
- Pull Requests: Revision de codigo y colaboracion
- Correo electronico: security@thirdkey.ai para problemas de seguridad
Directrices de Comunicacion:
- Ser claro y conciso
- Mantenerse en el tema
- Ser paciente y util
- Usar lenguaje inclusivo
- Respetar diferentes puntos de vista
Reconocimiento
Contribuyentes
Reconocemos y apreciamos todas las formas de contribucion:
- Contribuyentes de Codigo: Listados en CONTRIBUTORS.md
- Contribuyentes de Documentacion: Acreditados en la documentacion
- Reportadores de Errores: Mencionados en las notas de lanzamiento
- Investigadores de Seguridad: Acreditados en avisos de seguridad
Niveles de Contribuyentes
Contribuyente de la Comunidad:
- Enviar pull requests
- Reportar errores y problemas
- Participar en discusiones
Contribuyente Regular:
- Contribuciones de calidad consistente
- Ayudar a revisar pull requests
- Mentorizar nuevos contribuyentes
Mantenedor:
- Miembro del equipo principal
- Permisos de merge
- Gestion de lanzamientos
- Direccion del proyecto
Obtener Ayuda
Recursos
- Documentacion: Guias y referencias completas
- Ejemplos: Ejemplos de codigo funcional en
/examples - Pruebas: Casos de prueba que muestran el comportamiento esperado
- Issues: Buscar issues existentes para soluciones
Canales de Soporte
Soporte de la Comunidad:
- GitHub Issues para errores y solicitudes de funcionalidades
- GitHub Discussions para preguntas e ideas
- Stack Overflow con la etiqueta
symbiont
Soporte Directo:
- Correo electronico: support@thirdkey.ai
- Seguridad: security@thirdkey.ai
Preguntas Frecuentes
P: Como empiezo a contribuir? R: Comience configurando el entorno de desarrollo, leyendo la documentacion y buscando etiquetas “good first issue”.
P: Que habilidades necesito para contribuir? R: Programacion en Rust, conocimiento basico de seguridad y familiaridad con conceptos de IA/ML son utiles pero no requeridos para todas las contribuciones.
P: Cuanto tiempo toma la revision de codigo? R: Tipicamente de 1 a 3 dias habiles para cambios pequenos, mas tiempo para cambios complejos o sensibles a la seguridad.
P: Puedo contribuir sin escribir codigo? R: Si. La documentacion, las pruebas, los reportes de errores y las solicitudes de funcionalidades son contribuciones valiosas.
Proceso de Lanzamiento
Flujo de Trabajo de Desarrollo
graph LR
A[Feature Branch] --> B[Pull Request]
B --> C[Code Review]
C --> D[Testing]
D --> E[Merge to Main]
E --> F[Release Candidate]
F --> G[Security Review]
G --> H[Release]
Versionado
Symbiont sigue Versionado Semantico:
- Mayor (X.0.0): Cambios que rompen compatibilidad
- Menor (0.X.0): Nuevas funcionalidades, retrocompatible
- Parche (0.0.X): Correcciones de errores, retrocompatible
Calendario de Lanzamientos
- Lanzamientos de parche: Segun sea necesario para correcciones criticas
- Lanzamientos menores: Mensualmente para nuevas funcionalidades
- Lanzamientos mayores: Trimestralmente para cambios significativos
Proximos Pasos
Listo para contribuir? Asi es como empezar:
- Configure su entorno de desarrollo
- Encuentre un buen primer issue
- Unase a la discusion
- Lea la documentacion tecnica
Gracias por su interes en contribuir a Symbiont. Sus contribuciones ayudan a construir el futuro del desarrollo de software seguro y nativo de IA.