Homogenize /docs directory making sure it follows the instructions in .github

docs/articles/appendices/glossary.md

@@ -0,0 +1,64 @@
+# Glossary
+
+This article is about:
+- Key terms and concepts used in Hatch Schemas documentation
+- Definitions for technical terminology
+
+You will learn about:
+- The meaning of important terms in the Hatch ecosystem
+- Context for technical concepts used throughout the documentation
+
+## Core Concepts
+
+**Hatch Schema**
+: A JSON schema that defines the structure and validation rules for metadata in the CrackingShells package ecosystem.
+
+**JSON Schema**
+: A vocabulary that allows you to annotate and validate JSON documents. Uses JSON format to describe the structure, data types, and validation rules.
+
+**Package Metadata**
+: Structured information about a package including name, version, dependencies, author information, and other descriptive data.
+
+**Registry**
+: The central catalog of all available packages in the Hatch ecosystem, maintained as a searchable database.
+
+## Schema Types
+
+**Package Schema**
+: Schema for validating individual package metadata files (`hatch_pkg_metadata_schema.json`).
+
+**Registry Schema**
+: Schema for validating the central package registry structure (`hatch_all_pkg_metadata_schema.json`).
+
+## Validation Terms
+
+**Schema Validation**
+: The process of checking that a JSON document conforms to the rules defined in a JSON schema.
+
+**Version Constraint**
+: A specification defining which versions of a dependency are acceptable (e.g., `>=1.0.0`, `^2.1.0`).
+
+**Entry Point**
+: The main executable file or script that serves as the primary interface for a package.
+
+## Technical Terms
+
+**URI**
+: Uniform Resource Identifier - a string that identifies a resource, typically a URL.
+
+**Semantic Versioning**
+: A versioning scheme using three numbers (major.minor.patch) to indicate backwards compatibility.
+
+**Dependency**
+: An external package or component that a package requires to function properly.
+
+## Ecosystem Terms
+
+**CrackingShells**
+: The GitHub organization that maintains the Hatch package ecosystem.
+
+**Hatchling**
+: The build system and package manager for the Hatch ecosystem.
+
+**Package Manager**
+: A tool for installing, updating, and managing software packages (e.g., pip, apt, npm).

docs/articles/devs/Contributing.md

@@ -0,0 +1,63 @@
+# Contributing Guidelines
+
+This article is about:
+- How to contribute to the Hatch Schemas project
+- Development workflow and standards
+- Issue reporting and pull request processes
+
+You will learn about:
+- How to propose schema changes
+- Development setup and contribution workflow
+- Quality standards and review processes
+
+Contributions to Hatch Schemas help improve the standardization and reliability of the Hatch package ecosystem.
+
+## How to Contribute
+
+### Proposing Schema Changes
+
+To propose revisions to the schemas:
+
+1. **Open an Issue**: Create a detailed issue describing the proposed changes
+2. **Provide Rationale**: Explain why the change is needed and how it improves the ecosystem
+3. **Include Examples**: Show how the change would affect existing schemas
+4. **Consider Backwards Compatibility**: Discuss migration strategies for existing packages
+
+### Development Workflow
+
+1. **Fork the Repository**: Create your own fork of the project
+2. **Create a Feature Branch**: Use descriptive branch names
+3. **Make Changes**: Follow the project's coding standards
+4. **Test Changes**: Ensure all validation tests pass
+5. **Submit Pull Request**: Include detailed description of changes
+
+### Code Standards
+
+- **JSON Schema Format**: Follow JSON Schema Draft 7 specification
+- **Versioning**: Use semantic versioning for schema releases
+- **Documentation**: Update documentation for any schema changes
+- **Testing**: Include validation tests for new schema features
+
+## Issue Reporting
+
+When reporting issues:
+
+- Use clear, descriptive titles
+- Provide schema validation examples
+- Include expected vs actual behavior
+- Reference relevant schema versions
+
+## Review Process
+
+All contributions go through:
+
+1. **Automated Testing**: Schema validation and documentation checks
+2. **Peer Review**: Community review of proposed changes
+3. **Maintainer Approval**: Final review by project maintainers
+4. **Release Process**: Integration into versioned releases
+
+## See Also
+
+- [Development Setup](DevelopmentSetup.md)
+- [Repository Structure](RepositoryStructure.md)
+- [Schema Versioning](SchemaVersioning.md)

docs/articles/devs/DevelopmentSetup.md

@@ -0,0 +1,145 @@
+# Development Setup
+
+This article is about:
+- Setting up a development environment for Hatch Schemas
+- Required tools and dependencies
+- Testing and validation workflows
+
+You will learn about:
+- How to set up your development environment
+- How to run tests and validation
+- How to test schema changes locally
+
+Setting up a proper development environment ensures you can contribute effectively to the Hatch Schemas project.
+
+## Prerequisites
+
+- **Git**: For version control
+- **Python 3.8+**: For running validation scripts
+- **Node.js** (optional): For additional JSON schema tools
+
+## Setup Steps
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/CrackingShells/Hatch-Schemas.git
+cd Hatch-Schemas
+```
+
+### 2. Install Python Dependencies
+
+```bash
+# Install required packages for validation
+pip install jsonschema requests
+```
+
+### 3. Verify Setup
+
+```bash
+# Test schema loading
+python examples/schema_updater.py
+```
+
+## Development Workflow
+
+### Schema Validation
+
+Test your schema changes:
+
+```bash
+# Validate package schema
+python -c "
+import jsonschema
+import json
+
+# Load schema
+with open('package/v1.2.0/hatch_pkg_metadata_schema.json') as f:
+    schema = json.load(f)
+
+# Test with example data
+test_data = {
+    'package_schema_version': '1.2.0',
+    'name': 'test_package',
+    'version': '1.0.0',
+    'description': 'Test package',
+    'tags': ['test'],
+    'author': {'name': 'Test User'},
+    'license': {'name': 'MIT'},
+    'entry_point': 'main.py'
+}
+
+jsonschema.validate(test_data, schema)
+print('Schema validation passed!')
+"
+```
+
+### Testing Changes
+
+Before submitting changes:
+
+1. **Validate All Schemas**: Ensure JSON schema syntax is correct
+2. **Test Examples**: Verify example data validates against schemas
+3. **Update Documentation**: Keep documentation in sync with schema changes
+4. **Check CI**: Ensure automated tests pass
+
+### Local Testing
+
+Create test files to validate your changes:
+
+```bash
+# Create test package metadata
+cat > test_package.json << 'EOF'
+{
+  "$schema": "./package/v1.2.0/hatch_pkg_metadata_schema.json",
+  "package_schema_version": "1.2.0",
+  "name": "test_package",
+  "version": "1.0.0",
+  "description": "Test package for development",
+  "tags": ["test", "development"],
+  "author": {
+    "name": "Developer",
+    "email": "dev@example.com"
+  },
+  "license": {
+    "name": "MIT"
+  },
+  "entry_point": "main.py"
+}
+EOF
+
+# Validate with jsonschema
+python -c "
+import jsonschema
+import json
+
+with open('test_package.json') as f:
+    data = json.load(f)
+with open('package/v1.2.0/hatch_pkg_metadata_schema.json') as f:
+    schema = json.load(f)
+
+jsonschema.validate(data, schema)
+print('Validation successful!')
+"
+```
+
+## CI/CD Pipeline
+
+The project uses GitHub Actions for:
+
+- **Schema Validation**: Ensuring all schemas are valid JSON Schema documents
+- **Documentation Building**: Verifying documentation builds correctly
+- **Release Automation**: Publishing versioned releases
+
+## Debugging Tips
+
+- Use online JSON Schema validators for quick testing
+- Check schema syntax with JSON linters
+- Validate against multiple example files
+- Test both valid and invalid data
+
+## See Also
+
+- [Contributing Guidelines](Contributing.md)
+- [Repository Structure](RepositoryStructure.md)
+- [Schema Versioning](SchemaVersioning.md)