diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index da36dda..873a015 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -145,6 +145,7 @@ export default defineConfig({ text: 'Styling', collapsed: true, items: [ + { text: 'FAST-Graphics', link: '/stacks/frontend/styling/fastgraphics' }, { text: 'MaterialUI', link: '/stacks/frontend/styling/materialui' }, { text: 'TailwindCSS', link: '/stacks/frontend/styling/tailwindcss' }, ] diff --git a/docs/public/merge.png b/docs/public/merge.png new file mode 100644 index 0000000..9bbddae Binary files /dev/null and b/docs/public/merge.png differ diff --git a/docs/public/repository.png b/docs/public/repository.png new file mode 100644 index 0000000..2a47f08 Binary files /dev/null and b/docs/public/repository.png differ diff --git a/docs/public/taskid.png b/docs/public/taskid.png new file mode 100644 index 0000000..748db37 Binary files /dev/null and b/docs/public/taskid.png differ diff --git a/docs/public/versioning.png b/docs/public/versioning.png new file mode 100644 index 0000000..e5e550d Binary files /dev/null and b/docs/public/versioning.png differ diff --git a/docs/stacks/backend/python/fastapi.md b/docs/stacks/backend/python/fastapi.md index aaf7556..2e0f0be 100644 --- a/docs/stacks/backend/python/fastapi.md +++ b/docs/stacks/backend/python/fastapi.md @@ -8,7 +8,7 @@ FastAPI is a modern, fast (high-performance), web framework for building APIs wi It provides: - Speed: It is one of the fastest Python frameworks available. -. Auto-Documentation: It automatically generates interactive API documentation (Swagger UI) at /docs. You can test your API directly from the browser without any extra tools. +- Auto-Documentation: It automatically generates interactive API documentation (Swagger UI) at `/docs`. You can test your API directly from the browser without any extra tools. - Fewer Bugs: It uses Python type hints to catch errors early. If you expect an int and get a string, FastAPI automatically sends back a helpful error message to the client. - Standards-Based: It is built on open standards like JSON Schema and OAuth2. @@ -54,3 +54,86 @@ async def search(query: str, limit: int = 10): return {"results": f"Searching for {query}", "limit": limit} ``` +Run the server using typing `uvicorn :app --reload` in the terminal, in the project root folder. + +::: info +The path may be a simple `main`, or something like `backend.api` (no slashes, subfolder separation is with dots), or whatever you want. +::: + + +### Pydantic Integration + +```python +from pydantic import BaseModel + +class Item(BaseModel): + name: str + price: float + +@app.post("/items/") +async def create_item(item: Item): + return item +``` + +### CORS + +Critical for any frontend-backend setup (for example, Next.js calling the API). Without it, browsers will block requests: + +```python +from fastapi.middleware.cors import CORSMiddleware + +app.add_middleware( + CORSMiddleware, + allow_origins=["http://localhost:3000"], # frontend URL + allow_credentials=True, + allow_methods=["*"], + allow_headers=["*"], +) +``` + +### Response Models + +Very practical: prevents accidentally exposing sensible or unwanted fields in responses: + +```python +class UserOut(BaseModel): + id: int + username: str + +@app.get("/users/{id}", response_model=UserOut) +async def get_user(id: int): ... +``` + +### Error Handling + +```python +from fastapi import HTTPException + +@app.get("/users/{user_id}") +async def get_user(user_id: int): + if user_id not in db: + raise HTTPException(status_code=404, detail="User not found") +``` + + +### Dependency Injection + +FastAPI's `Depends` system is a standout feature used for auth, DB sessions, etc. Even a one-liner pointing to the concept is useful: + +```python +from fastapi import Depends + +def get_db(): + db = SessionLocal() + try: + yield db + finally: + db.close() + +@app.get("/items/") +def read_items(db = Depends(get_db)): ... +``` + +--- + +See additional examples on the official docs: https://fastapi.tiangolo.com/ \ No newline at end of file diff --git a/docs/stacks/backend/python/pydantic.md b/docs/stacks/backend/python/pydantic.md index 251bd3a..ea21ba2 100644 --- a/docs/stacks/backend/python/pydantic.md +++ b/docs/stacks/backend/python/pydantic.md @@ -73,4 +73,56 @@ except ValidationError as e: print(e.json()) # Returns a detailed explanation of why it failed ``` +The current example is 'flat'. In practice, models nest inside each other (for example, a Project has a list of Users). This is the most direct bridge to how you'd use Pydantic with FastAPI request/response bodies: + +```python +class Address(BaseModel): + city: str + country: str + +class Employee(BaseModel): + name: str + address: Address # nested model +``` + + +### Model Validator + + A very common real-world need is validating relationships between fields (for example, `end_date` must be after `start_date`). This is one of the most asked-about Pydantic features: + +```python +from pydantic import BaseModel, model_validator + +class DateRange(BaseModel): + start: int + end: int + + @model_validator(mode="after") + def check_range(self) -> "DateRange": + if self.end <= self.start: + raise ValueError("end must be greater than start") + return self +``` + + +### Pydantic Settings + +This is a separate but closely related package that can become really handy. It reads `.env` files and environment variables into a validated Pydantic model, central to any FastAPI project: + +```python +from pydantic_settings import BaseSettings + +class Settings(BaseSettings): + database_url: str + api_key: str + debug: bool = False + + class Config: + env_file = ".env" + +settings = Settings() +``` + +--- + See more suitable examples on the official docs: https://pydantic.dev/docs/validation/latest/examples/files/ \ No newline at end of file diff --git a/docs/stacks/frontend/styling/fastgraphics.md b/docs/stacks/frontend/styling/fastgraphics.md new file mode 100644 index 0000000..f854f92 --- /dev/null +++ b/docs/stacks/frontend/styling/fastgraphics.md @@ -0,0 +1,9 @@ +--- +outline: deep +--- + +# FAST-Graphics + +`@fast-computing/fast-graphics` is the official internal UI & graphics library for company web applications and websites. Built on TypeScript, it provides fully typed, accessible, and performant web components, canvas utilities, and layout primitives. + +Full documentation is at https://github.com/FAST-Computing/fast-graphics \ No newline at end of file diff --git a/docs/tools/coding/git.md b/docs/tools/coding/git.md index e1682d0..28ae419 100644 --- a/docs/tools/coding/git.md +++ b/docs/tools/coding/git.md @@ -6,7 +6,20 @@ outline: deep Git is the engine under the hood, and GitHub is the shiny showroom where everyone sees your work. Mastering a handful of core commands will handle 90% of your daily workflow. -## Installation +Think of Git as a three-stage process for saving your work. You move files from your folder to a "staging area" before finally sealing them into the permanent history (the repository). + +In most cases, you would normally like to work on your, personal branch, unless stated otherwise. Branches allow you to work on new features without breaking the "main" (stable) version of the project. You should switch to your branch before committing any file. + +- `git checkout -b `: Create and switch to a new branch. +- `git add `: Move changes to the Staging Area. Use `git add .` to stage everything instead. +- `git commit -m "Your message"`: Record the staged changes permanently. Remember, keep messages descriptive (e.g., "Fix login button styling"). + +![Branch check](/branchcheck.png) +In VSCode, you can monitor the branch you're working in by looking at the bottom left of the screen or you can use `git status`, a very helpful command you can always run to additionally check local files status. + +## Setup + +### Installation ::: code-group @@ -16,7 +29,7 @@ pacman -S git ::: -## SSH Key +### SSH Key You will need an SSH key so that your computer and GitHub will have a "secret handshake" that identifies you automatically, without needing any further authentication. @@ -48,13 +61,11 @@ ssh -T git@github.com If you see *"Hi [YourUsername]! You've successfully authenticated"*, everything is set and you are ready to go. -## New Project Set-Up - -When setting up a new project, always start by creating a new GitHub repository named **`fast-projectname`**. +## Working on a Project -It must contain the code, script environment, CI/CD and setup READMI. +### Repository Initialization -## Repository Initialization +If you need to work on an existing repository, just clone it locally: - `git clone `: Download an existing GitHub repository to your computer @@ -64,38 +75,214 @@ You can get the required URL pushing the green "Code" button and copying the SSH - `git init`: Git initialization in current folder - `git remote add origin `: Connect the local repository to the GitHub one +Else, when setting up a new project, always start by creating a new GitHub repository named **`fast-`** followed by the name of your project. + + +### Conventions + +The current company workflow is structured in the following way: +- `main` (production): the root and stable branch containing the production, functional code for final users; +- `dev` (test/pre-production): the branch (or environment) into which the code is integrated to simulate the production environment and perform integration testing and QA. +- `feature/` (development): temporary branches created by each developer/contributor in order to implement new functionalities, resolve bugs and so on, without touching the main code. + +Core Rules: +- **Mandatory Task ID**: Every single piece of development starts from a task (e.g., `TASK-123`). The ID must be taken from the respective GoodDay task and always be included in branches, commits, and PRs. + +![TaskID](/taskid.png) + +- **No Direct Push to `main` or `dev`**: Updating the primary branches is done exclusively via Pull Requests. +- **Mandatory Rebase**: Do not run `git merge main` inside your feature branch. Always align your branch using `rebase`. + +Branch Naming Conventions: +- **Feature**: `feature/TASK-123-description` +- **Bugfix**: `bugfix/TASK-211-login-error` +- **Hotfix**: `hotfix/TASK-300-fix-payment` +- **Refactoring**: `refactor/TASK-500-clean-services` +- **Spike/Test**: `spike/TASK-700-oauth-test` + +Commit Naming Conventions: +- **Format**: `TASK-123 short description` + ## Core Workflow -Think of Git as a three-stage process for saving your work. You move files from your folder to a "staging area" before finally sealing them into the permanent history (the repository). +In FAST-Computing, we decided to take the following approach: -- `git add `: Move changes to the Staging Area. Use `git add .` to stage everything instead. -- `git commit -m "Your message"`: Record the staged changes permanently. Remember, keep messages descriptive (e.g., "Fix login button styling"). +#### 1. Creating the Development Branch -However, you would normally like to work on your, personal branch, unless stated otherwise. Branches allow you to work on new features without breaking the "Main" (stable) version of the project. +Before starting any task, switch to the `dev` branch and pull the latest changes from remote: -- `git checkout -b `: Create and switch to a new branch. +```sh +# Switch to dev and update it +git checkout dev +git pull origin dev -![Branch check](/branchcheck.png) -In VSCode, you can monitor the branch you're working in by looking at the bottom left of the screen. +# Create your working branch from dev +git checkout -b feature/TASK-123-export-pdf +``` -- `git status`: A very helpful command you can always run to check files status and the current branch. +#### 2. Frequent Development & Commits -## Pushing to GitHub +Work on your code and commit frequently following the naming convention: -To share your code, you need to link your local folder to the remote repository on GitHub. +```sh +# Check modified files +git status -- `git push -u origin main`: Send your local commits to GitHub. The `-u` flag remembers your preferences for next time. -- `git pull`: Grab the latest changes from GitHub and merge them into your local files. Use this often to stay up to date with workmates. +# Stage your changes +git add . -::: warning -Instead of doing `git pull` directly, it is wisely recommended, instead, to `git fetch ` first - to download new commits without touching working files - and then `git rebase ` to move your local, unpushed commits to sit "on top" of the fetched commits from the server. -::: +# Create the commit +git commit -m "TASK-123 add base layout for PDF export" + +# Push your changes to the remote repository (first push) +git push -u origin feature/TASK-123-export-pdf +``` + +#### 3. Rebase onto main before opening/merging the PR + +Before opening (or merging) your Pull Request, align your branch with main to ensure a clean, linear history: + +```sh +# Fetch latest data from origin without merging +git fetch origin + +# Rebase your work onto origin/main +git rebase origin/main + +# If there are conflicts: resolve them in your files, stage them, and continue: +# git add +# git rebase --continue + +# Force-push changes safely to the remote branch +git push --force-with-lease +``` + +#### 4. Opening and Merging the PR into dev + +- Open a Pull Request on GitHub setting base: `dev` and compare: `feature/TASK-123-export-pdf` (PR Title: `TASK-123 - Export PDF`). +- Verify PR pre-merge requirements: + - Green CI (build, test, lint pass) + - No merge conflicts + - At least 1 team approval + - All conversations resolved + - No critical warnings +- Select `Squash and Merge` (resulting commit: `TASK-123 Export PDF`). +- Delete the remote branch (automated via GitHub or manually). + +```sh +# Local cleanup after merging the PR +git checkout dev +git pull origin dev +git branch -d feature/TASK-123-export-pdf +git fetch --prune +``` + + +### Production Hotfix + +If a critical bug occurs in production that requires an immediate patch: + +Create the Hotfix Branch from `main`: + +```sh +git checkout main +git pull origin main +git checkout -b hotfix/TASK-300-fix-payment +``` + +Quick Fix & Commit: + +```sh +git add . +git commit -m "TASK-300 fix payment gateway timeout" +git push -u origin hotfix/TASK-300-fix-payment +``` + +PR & Immediate Merge into `main`: +- Open a PR with base: `main`. +- Request a quick review and wait for CI checks to pass. +- Perform a `Squash and Merge`. +- Deploy the fix to production immediately. + +To prevent code drift, align `dev` with `main` right after merging the hotfix: + +```sh +# Switch to dev and update it +git checkout dev +git pull origin dev + +# Rebase dev onto origin/main +git fetch origin +git rebase origin/main + +# Push updated dev branch safely +git push --force-with-lease +``` + +Extra Commands Cheat Sheet: +- `git status`: Check the state of modified/staged files. +- `git log --oneline --graph`: View a concise, graphical representation of commit history. +- `git fetch --prune`: Remove stale local tracking branches that were deleted on remote. + + +## Structures + +### Repository Branches + +![Repository](/repository.png) + +### Development Flow + +![Flow](/merge.png) + + +## Versioning + +The best and most standardized way to manage versioning is adopting semantic versioning combined with git tags. + +The version number follows the vX.Y.Z structure: +- `MAJOR` (X): Major changes or breaking changes (incompatibility with the previous version, e.g., API rewrites, non-backward-compatible database changes). +- `MINOR` (Y): New features released in a backward-compatible manner. +- `PATCH` (Z): Bug fixes (bugfix/hotfix) or small backward-compatible optimizations. + +![Versioning](/versioning.png) + +### Ordinary Releases (dev ➔ main) + +Every time you complete a set of tasks on `dev` and open a PR toward `main`: +- Version evaluation: + - If the release contains only new features/refactorings, increment `MINOR` (e.g., v1.2.0 -> v1.3.0). + - If it contains breaking changes, increment `MAJOR` (e.g., v1.2.0 -> v2.0.0). + +After merging the Release PR into `main`, an annotated tag is created directly on the release commit: + +```sh +git checkout main +git pull origin main + +# Create the annotated tag with a message +git tag -a v1.3.0 -m "Release v1.3.0: Include TASK-123, TASK-124, TASK-125" + +# Push the tag on GitHub +git push origin v1.3.0 +``` + +### Emergency Hotfix (hotfix/* ➔ main) + +When you apply a patch on `main`: always increase `PATCH` (es. v1.3.0 -> v1.3.1). + +```sh +git checkout main +git pull origin main + +git tag -a v1.3.1 -m "Hotfix v1.3.1: critical fix payment TASK-300" +git push origin v1.3.1 +``` + +## Actions -## Pull Requests +GitHub Actions are very useful workflows to be included or recalled from your repositories, with the purpose of automating checks, deployments, guardrails, tests. -A **Pull Request** (PR) isn't a Git command; it’s a GitHub feature. It’s a formal request to merge your branch into the main project and you can do it by going to the GitHub repository page. It allows for: +FAST-Computing's workflows are currently stored in https://github.com/FAST-Computing/.github, from which they can be directly recalled in your applications. -- Code Review: Others can comment on specific lines. -- Testing: Automated tools can check if your code breaks anything. -- Discussion: A place to talk about why the changes were made. \ No newline at end of file diff --git a/docs/tools/productivity/goodday.md b/docs/tools/productivity/goodday.md index 4bb33d2..a74c140 100644 --- a/docs/tools/productivity/goodday.md +++ b/docs/tools/productivity/goodday.md @@ -6,4 +6,95 @@ outline: deep https://www.goodday.work/ -For more information watch the video tutorials here: https://www.goodday.work/video-tutorials \ No newline at end of file +Welcome to the internal project management guidelines for **GoodDay**. This document outlines the hierarchy, board statuses, tracking conventions, and task ownership rules to ensure consistency and accurate time tracking across all teams. + + +## Project Hierarchy + +To keep our workflows structured, GoodDay utilizes two main organizational models depending on the nature of the work. + +### Project-Based Structure + +For standard projects broken down into Work Packages (WPs) or specific execution phases: + +* **RESOURCE** *(Project Name)* + * **Work Project** *(WP or Phase)* + * **Task** *(WP: Main Assignee)* + * **Subtask** *(Implementation Task)* + * **Checklist** *(Optional granular breakdown)* + + +### Non-Project / Macro Area Structure + +For ongoing operations, continuous improvements, or non-project macro areas: + +* **RESOURCE** *(Macro Area Name)* + * **Macro Task** *(Intervention / Initiative)* + * **Task** *(Intervention: Main Assignee)* + * **Subtask** *(Implementation Task)* + * **Checklist** *(Optional granular breakdown)* + + +## Team Allocation & Task Assignment Rules + +### Initial Team Listing + +At the start of every project, initial tasks must be placed at the root/top level to define and list the assigned team members: +> **Example:** `WP0: Pippo`, `WP0: Pluto`, `WP0: Paperoga` + +### Dynamic Reassignment + +* A dedicated set of developers will be assigned to each project to handle subtasks. +* **Reassignment Rule:** If a task is executed or implemented by a developer other than the originally assigned primary owner, **the task must be moved under the corresponding WP of the developer actually implementing it.** + + +## Mandatory Rules & Estimations + +::: warning +Every single task located inside project folders **MUST contain an estimate**. + +* **Why?** If any task is missing an estimate, the overall project folder will fail to calculate and display the total aggregated estimate. +* **Fallback:** If an exact estimate cannot be determined, set the estimate value to **`0`**. +::: + + +## Kanban Board & Workflow Statuses + +### Available Board Columns + +Our Kanban board uses the following standard workflow stages: + +1. `Not Started` +2. `Continuous` +3. `MACRO In Progress` +4. `In Progress` +5. `Review` +6. `On Hold` +7. `Closed` + + +### Status Progression Rules + +To prevent confusion and maintain visibility across parent and child items, follow this exact workflow: + +``` +[Start Task / WP] ---> Task & Parent Macro Task / WP set to "In Progress" + | + v +[All Subtasks in Review] ---> Parent Macro Task / WP moves to "Review" + | + v +[All Subtasks Closed] ---> Parent Macro Task / WP moves to "Closed" +``` + +* **Starting Work:** As soon as work begins on a child Task (or Work Package), both the specific **Task** and its parent **Macro Task / WP** must be set to `In Progress`. +* **Moving to Review:** A parent **Macro Task / WP** transitions to `Review` only when **all** underlying tasks are in `Review`. +* **Closing Work:** A parent **Macro Task / WP** transitions to `Closed` only when **all** underlying tasks are marked `Closed`. + + +## Time Tracking & Logging Guidelines + +Accurate time logging is essential for reporting and auditing. + +* **Primary Method:** Always log worked hours directly on the **Subtask** level whenever possible. +* **Exception:** Time may be logged on the main **Task** level only in exceptional, justified circumstances. \ No newline at end of file