Merge pull request #7 from metacall/docs

docs: initial documentation for MetaSSR

.github/workflows/release.yml

@@ -0,0 +1,93 @@
+name: Release
+
+permissions:
+  contents: write
+
+on:
+  push:
+    tags:
+      - v[0-9]+.*
+
+env:
+  CARGO_INCREMENTAL: 0
+
+jobs:
+  release:
+    name: ${{ matrix.target }}
+    permissions:
+      contents: write
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - os: ubuntu-latest
+            target: aarch64-unknown-linux-gnu
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+
+      - name: Get version
+        id: get_version
+        uses: SebRollen/[email protected]
+        with:
+          file: Cargo.toml
+          field: package.version
+
+      - name: Set artifact name
+        shell: bash
+        run: |
+          version="$(git describe --tags --match='v*' --always)"
+          name="metassr-$version-${{ matrix.target }}"
+          echo "ARTIFACT_NAME=$name" >> $GITHUB_ENV
+          echo "version: $version"
+          echo "artifact: $name"
+      - name: Install Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          profile: minimal
+          override: true
+          target: ${{ matrix.target }}
+
+      - name: Setup cache
+        uses: Swatinem/rust-cache@v1
+
+      - name: Build binary
+        uses: actions-rs/cargo@v1
+        with:
+          command: build
+          args: --release --locked --target=${{ matrix.target }} --color=always --verbose
+          use-cross: ${{ runner.os == 'Linux' }}
+
+      - name: Package (*nix)
+        run: >
+          echo "install -Dm755 ./metassr /usr/bin" > "install.sh" && 
+          tar -cv
+          install.sh LICENSE README.md ./docs/
+          -C target/${{ matrix.target }}/release/ metassr-cli
+          | gzip --best
+          > 'metassr-${{ steps.get_version.outputs.value }}-${{ matrix.target }}.tar.gz'
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: ${{ matrix.target }}
+          path: |
+            *.deb
+            *.tar.gz
+            *.zip
+      - name: Create release
+        uses: softprops/action-gh-release@v1
+        with:
+          draft: true
+          files: |
+            *.deb
+            *.tar.gz
+            *.zip
+          name: ${{ steps.get_version.outputs.value }}

CODE_OF_CONDUCT.md

@@ -0,0 +1,54 @@
+# Code of Conduct
+
+## Introduction
+
+As a member of the MetaSSR community, we are committed to creating a welcoming and inclusive environment for everyone. This Code of Conduct outlines our expectations for behavior and provides guidance on how to address inappropriate conduct.
+
+## Our Pledge
+
+We pledge to make participation in the MetaSSR community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- **Be Respectful**: Treat all community members with respect and kindness. Engage in constructive discussions and provide support to others.
+- **Be Inclusive**: Encourage and welcome diverse perspectives and experiences. Foster an environment where everyone feels valued and heard.
+- **Be Professional**: Communicate professionally and with empathy. Avoid using discriminatory, derogatory, or offensive language.
+- **Be Collaborative**: Work collaboratively with others. Offer assistance, share knowledge, and work towards common goals.
+
+Examples of unacceptable behavior include:
+
+- **Harassment**: Unwelcome and offensive comments, threats, or actions. This includes but is not limited to harassment based on race, gender, sexual orientation, disability, or any other characteristic.
+- **Discrimination**: Exclusion or unfair treatment based on personal characteristics or background.
+- **Personal Attacks**: Engaging in personal attacks or targeting individuals with derogatory comments or behavior.
+- **Unwelcome Behavior**: Any behavior that interferes with others’ participation or enjoyment of the community.
+
+## Enforcement
+
+If you witness or experience any behavior that violates this Code of Conduct, please report it to the community maintainers. Reports can be submitted through our issue tracker on [GitHub](https://github.com/metacall/metassr/issues).
+
+We will review and address all reports promptly. Depending on the severity of the violation, actions may include:
+
+- **Warning**: Issuing a warning to the individual regarding their behavior.
+- **Temporary Suspension**: Temporarily suspending the individual’s access to community resources.
+- **Permanent Ban**: Removing the individual from the community permanently if necessary.
+
+## Scope
+
+This Code of Conduct applies to all community spaces and interactions related to MetaSSR, including but not limited to:
+
+- Online forums and discussions
+- Code contributions and pull requests
+- In-person events or meetings
+
+## Acknowledgment
+
+By participating in the MetaSSR community, you acknowledge that you have read and agreed to abide by this Code of Conduct.
+
+## Changes
+
+We may update this Code of Conduct from time to time. The updated version will be posted in this repository, and all community members will be notified of significant changes.
+
+Thank you for helping us create a positive and inclusive community!
+

CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing to MetaSSR
+
+Thank you for your interest in contributing to MetaSSR! We welcome contributions from the community to help improve and expand the framework. Please follow the guidelines below to ensure your contributions are effective and align with the project's goals.
+
+## How to Contribute
+
+### 1. Reporting Issues
+
+If you encounter a bug or have a suggestion for a new feature, please report it using the following steps:
+
+1. **Check Existing Issues**: Before creating a new issue, search the [issue tracker](https://github.com/metacall/metassr/issues) to see if your issue or feature request has already been reported.
+2. **Create a New Issue**: If your issue is not listed, create a new issue with a clear and descriptive title. Provide as much detail as possible about the problem or feature request.
+
+### 2. Submitting Code Contributions
+
+To contribute code, follow these steps:
+
+1. **Fork the Repository**: Fork the MetaSSR repository to your own GitHub account. You can do this by clicking the "Fork" button at the top right of the repository page.
+2. **Clone Your Fork**: Clone your forked repository to your local machine using the following command:
+
+   ```bash
+   git clone https://github.com/yourusername/metassr.git
+   ```
+
+3. **Create a Branch**: Create a new branch for your changes. Use a descriptive name for the branch that reflects the nature of your work:
+
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+4. **Make Changes**: Implement your changes in the new branch. Ensure that your code adheres to the project's coding standards and guidelines.
+
+5. **Write Tests**: Add or update tests to ensure your changes are covered. We use [testing framework] for our tests, and you can find existing tests in the `tests` directory.
+
+6. **Commit Changes**: Commit your changes with a clear and concise commit message. Follow the [commit message conventions](#commit-message-conventions) for consistency:
+
+   ```bash
+   git add .
+   git commit -m "Add feature: Description of the feature"
+   ```
+
+7. **Push Changes**: Push your changes to your forked repository:
+
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+8. **Create a Pull Request**: Go to the [pull requests page](https://github.com/metacall/metassr/pulls) of the original repository and create a new pull request. Provide a detailed description of your changes and any relevant information.
+
+### 3. Code Review and Merge
+
+Once your pull request is submitted, it will be reviewed by the project maintainers. They may request changes or provide feedback. Please be responsive to their comments and make any necessary adjustments.
+
+### 4. Coding Standards
+
+- **Code Style**: Follow the coding style and conventions used in the existing codebase. This includes indentation, naming conventions, and code organization.
+- **Documentation**: Update or add documentation as needed. Ensure that your code changes are reflected in the project documentation.
+
+### 5. Commit Message Conventions
+
+Use clear and descriptive commit messages that follow this format:
+
+- **Type**: A short description of the change (e.g., `feat`, `fix`, `refactor`, `chore`, `doc`).
+- **Scope**: A brief description of the affected area (optional).
+- **Description**: A concise explanation of the change.
+
+**Examples:**
+
+```
+feat(cli): new cool feature in the cli 
+fix(builder): fix a bug in building operation
+```
+
+### 6. Testing
+
+Make sure your changes pass all existing and new tests. Run the tests locally before submitting your pull request:
+
+```bash
+cargo test
+```
+
+also, you can test one of web applications that located at [tests](../../tests/) directory.
+
+**Example:**
+```bash
+$ cargo run --bin metassr-cli -- --root=tests/web-app --debug-mode=all run 
+```
+
+
+### 7. Code of Conduct
+
+Please adhere to our [Code of Conduct](code-of-conduct.md) while participating in the MetaSSR community.
+
+## Getting Help
+
+If you have any questions or need assistance, feel free to reach out to us through the project's [discussion forum](https://github.com/metacall/metassr/discussions) or open an issue.
+
+Thank you for contributing to MetaSSR!
+

LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Mohamed Emad ([email protected])
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

README.md

@@ -1,16 +1,63 @@
 > **Warning**  
-> this project under development, **Don't use it in production**.
+> this project under development, **Using it is your responsibility**.
 
 <div align="center">
  <h1>MetaSSR</h1>
 
 <p align='center'> SSR framework for React.js built on <a href="https://github.com/metacall/core">MetaCall</a> </p>
 </div>
 
-## Running 
-```terminal
-$ cargo run --bin metassr-cli --root=tests/web-app
-```
 
+MetaSSR is a powerful Server-Side Rendering (SSR) framework crafted for high-performance, dynamic web applications. Built on Rust and leveraging the Axum web framework, MetaSSR integrates seamlessly with the Metacall platform, showcasing a real-world use case for polyglot programming.
 
+## Why MetaSSR?
+
+MetaSSR combines the robustness of Rust with the flexibility of Metacall and the simplicity of Axum to deliver a framework that's both fast and versatile. Whether you're building complex web applications or straightforward static sites, MetaSSR provides the tools and performance you need.
+
+### Key Features
+
+- **Rust-Powered Performance**: Enjoy the speed and safety of Rust in your server-side rendering tasks.
+- **High Performance with Axum.rs**: Achieve fast load times and excellent user experiences with optimized server-side rendering.
+- **Comprehensive CLI**: Manage your MetaSSR projects effortlessly using our powerful command-line interface.
+- **API Route with Polyglot Programming (SOON)**: Integrate multiple languages seamlessly with Metacall's support.
+
+## Getting Started
+
+To get started with MetaSSR, follow these steps:
+
+1. **Installation**: Review our [Installation Guide](docs/getting-started/installation.md) to install MetaSSR on your system.
+2. **CLI Documentation**: Learn how to utilize the MetaSSR CLI with our [CLI Documentation](docs/getting-started/cli.md).
+
+
+## Contributing
+
+We welcome contributions from the community! If you’re interested in helping out, please check out our [Contributing Guide](CONTRIBUTING.md) for information on how to get involved.
+
+## Code of Conduct
+
+To ensure a positive and inclusive environment, please review our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Community
+
+Stay connected and updated with MetaSSR:
+
+- **GitHub**: [MetaSSR Repository](https://github.com/metacall/metassr)
+- **Discussion Forum**: [Join the Conversation](https://github.com/metacall/metassr/discussions)
+- **Twitter**: [Follow US](https://twitter.com/metacallio)
+- **Metacall Community**: 
+  - [Discord](https://discord.gg/upwP4mwJWa)
+  - [Telegram](https://t.me/joinchat/BMSVbBatp0Vi4s5l4VgUgg)
+  - [Matrix](https://matrix.to/#/#metacall:matrix.org)
+
+## License
+
+MetaSSR is licensed under the [MIT License](LICENSE). See the LICENSE file for more details.
+
+## Acknowledgments
+
+A big thank you to the Metacall team for their incredible platform, and to the Rust and Axum communities for their tools and support. We also appreciate all contributors and supporters of the project.
+
+---
+
+We hope you enjoy working with MetaSSR as much as we do. Happy coding!