diff --git a/.cursor/rules/general-code-commenting.mdc b/.cursor/rules/general-code-commenting.mdc new file mode 100644 index 0000000..bd37355 --- /dev/null +++ b/.cursor/rules/general-code-commenting.mdc @@ -0,0 +1,11 @@ +--- +description: +globs: +alwaysApply: true +--- +--- +description: Ensures helpful comments are added to the code and that old, relevant comments are preserved. +globs: **/*.* +--- +- Always add helpful comments to the code explaining what you are doing. +- Never delete old comments, unless they are no longer relevant because the code has been rewritten or deleted. \ No newline at end of file diff --git a/.cursor/rules/naming-conventions-rule.mdc b/.cursor/rules/naming-conventions-rule.mdc new file mode 100644 index 0000000..e95c23c --- /dev/null +++ b/.cursor/rules/naming-conventions-rule.mdc @@ -0,0 +1,12 @@ +--- +description: +globs: +alwaysApply: true +--- +--- +description: Enforces specific naming conventions for React and TypeScript code to maintain consistency. +globs: **/*.{ts,tsx,js,jsx} +--- +- Follow standard TypeScript and JavaScript naming conventions for variables, functions, and components. +- Component names should be PascalCase. +- Variable and function names should be camelCase. \ No newline at end of file diff --git a/.cursor/rules/performance-optimization-rule.mdc b/.cursor/rules/performance-optimization-rule.mdc new file mode 100644 index 0000000..0565a54 --- /dev/null +++ b/.cursor/rules/performance-optimization-rule.mdc @@ -0,0 +1,13 @@ +--- +description: +globs: +alwaysApply: true +--- +--- +description: Rules to optimize performance of React and TypeScript components. +globs: **/*.{ts,tsx,js,jsx} +--- +- Optimize React component rendering using memoization techniques (e.g., React.memo). +- Avoid unnecessary re-renders. +- Lazy load components and images when possible. +- Use efficient data structures and algorithms. \ No newline at end of file diff --git a/.cursor/rules/react-and-typescript-general-rules.mdc b/.cursor/rules/react-and-typescript-general-rules.mdc new file mode 100644 index 0000000..a460911 --- /dev/null +++ b/.cursor/rules/react-and-typescript-general-rules.mdc @@ -0,0 +1,23 @@ +--- +description: +globs: +alwaysApply: true +--- +--- +description: General rules for React and TypeScript projects, focusing on code clarity and best practices. +globs: **/*.{ts,tsx,js,jsx} +--- +- You are an expert AI programming assistant that primarily focuses on producing clear, readable React and TypeScript code. +- You always use the latest stable version of TypeScript, JavaScript, React, Node.js, Tanstack Start, Shaden UI, Tailwind CSS v4 and you are familiar with the latest features and best practices. +- You are thoughtful, give nuanced answers, and are brilliant at reasoning. You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning. +- Follow the user’s requirements carefully & to the letter. +- First think step-by-step - describe your plan for what to build in pseudocode, written out in great detail. +- Confirm, then write code! +- Always write correct, up to date, bug free, fully functional and working, secure, performant and efficient code. +- Focus on readability over being performant. +- Fully implement all requested functionality. +- Leave NO todo’s, placeholders or missing pieces. +- Ensure code is complete! Verify thoroughly finalized. +- Include all required imports, and ensure proper naming of key components. +- Be concise. Minimize any other prose. +- If you think there might not be a correct answer, you say so. If you do not know the answer, say so instead of guessing. If you do not know the answer, say so instead of guessing. diff --git a/.cursor/rules/tailwind-css-v4.mdc b/.cursor/rules/tailwind-css-v4.mdc new file mode 100644 index 0000000..eb01c1c --- /dev/null +++ b/.cursor/rules/tailwind-css-v4.mdc @@ -0,0 +1,223 @@ +--- +description: +globs: +alwaysApply: true +--- +// Update globs depending on your framework +--- +name: tailwind_v4 +description: Guide for using Tailwind CSS v4 instead of v3.x +globs: ["**/*.{js,ts,jsx,tsx,mdx,css}"] +tags: + - tailwind + - css +--- + +# Tailwind CSS v4 + +## Core Changes + +- **CSS-first configuration**: Configuration is now done in CSS instead of JavaScript + - Use `@theme` directive in CSS instead of `tailwind.config.js` + - Example: + ```css + @import "tailwindcss"; + + @theme { + --font-display: "Satoshi", "sans-serif"; + --breakpoint-3xl: 1920px; + --color-avocado-500: oklch(0.84 0.18 117.33); + --ease-fluid: cubic-bezier(0.3, 0, 0, 1); + } + ``` +- Legacy `tailwind.config.js` files can still be imported using the `@config` directive: + ```css + @import "tailwindcss"; + @config "../../tailwind.config.js"; + ``` +- **CSS import syntax**: Use `@import "tailwindcss"` instead of `@tailwind` directives + - Old: `@tailwind base; @tailwind components; @tailwind utilities;` + - New: `@import "tailwindcss";` + +- **Package changes**: + - PostCSS plugin is now `@tailwindcss/postcss` (not `tailwindcss`) + - CLI is now `@tailwindcss/cli` + - Vite plugin is `@tailwindcss/vite` + - No need for `postcss-import` or `autoprefixer` anymore + +- **Native CSS cascade layers**: Uses real CSS `@layer` instead of Tailwind's custom implementation + +## Theme Configuration + +- **CSS theme variables**: All design tokens are available as CSS variables + - Namespace format: `--category-name` (e.g., `--color-blue-500`, `--font-sans`) + - Access in CSS: `var(--color-blue-500)` + - Available namespaces: + - `--color-*` : Color utilities like `bg-red-500` and `text-sky-300` + - `--font-*` : Font family utilities like `font-sans` + - `--text-*` : Font size utilities like `text-xl` + - `--font-weight-*` : Font weight utilities like `font-bold` + - `--tracking-*` : Letter spacing utilities like `tracking-wide` + - `--leading-*` : Line height utilities like `leading-tight` + - `--breakpoint-*` : Responsive breakpoint variants like `sm:*` + - `--container-*` : Container query variants like `@sm:*` and size utilities like `max-w-md` + - `--spacing-*` : Spacing and sizing utilities like `px-4` and `max-h-16` + - `--radius-*` : Border radius utilities like `rounded-sm` + - `--shadow-*` : Box shadow utilities like `shadow-md` + - `--inset-shadow-*` : Inset box shadow utilities like `inset-shadow-xs` + - `--drop-shadow-*` : Drop shadow filter utilities like `drop-shadow-md` + - `--blur-*` : Blur filter utilities like `blur-md` + - `--perspective-*` : Perspective utilities like `perspective-near` + - `--aspect-*` : Aspect ratio utilities like `aspect-video` + - `--ease-*` : Transition timing function utilities like `ease-out` + - `--animate-*` : Animation utilities like `animate-spin` + + +- **Simplified theme configuration**: Many utilities no longer need theme configuration + - Utilities like `grid-cols-12`, `z-40`, and `opacity-70` work without configuration + - Data attributes like `data-selected:opacity-100` don't need configuration + +- **Dynamic spacing scale**: Derived from a single spacing value + - Default: `--spacing: 0.25rem` + - Every multiple of the base value is available (e.g., `mt-21` works automatically) + +- **Overriding theme namespaces**: + - Override entire namespace: `--font-*: initial;` + - Override entire theme: `--*: initial;` + + +## New Features + +- **Container query support**: Built-in now, no plugin needed + - `@container` for container context + - `@sm:`, `@md:`, etc. for container-based breakpoints + - `@max-md:` for max-width container queries + - Combine with `@min-md:@max-xl:hidden` for ranges + +- **3D transforms**: + - `transform-3d` enables 3D transforms + - `rotate-x-*`, `rotate-y-*`, `rotate-z-*` for 3D rotation + - `scale-z-*` for z-axis scaling + - `translate-z-*` for z-axis translation + - `perspective-*` utilities (`perspective-near`, `perspective-distant`, etc.) + - `perspective-origin-*` utilities + - `backface-visible` and `backface-hidden` + +- **Gradient enhancements**: + - Linear gradient angles: `bg-linear-45` (renamed from `bg-gradient-*`) + - Gradient interpolation: `bg-linear-to-r/oklch`, `bg-linear-to-r/srgb` + - Conic and radial gradients: `bg-conic`, `bg-radial-[at_25%_25%]` + +- **Shadow enhancements**: + - `inset-shadow-*` and `inset-ring-*` utilities + - Can be composed with regular `shadow-*` and `ring-*` + +- **New CSS property utilities**: + - `field-sizing-content` for auto-resizing textareas + - `scheme-light`, `scheme-dark` for `color-scheme` property + - `font-stretch-*` utilities for variable fonts + +## New Variants + +- **Composable variants**: Chain variants together + - Example: `group-has-data-potato:opacity-100` + +- **New variants**: + - `starting` variant for `@starting-style` transitions + - `not-*` variant for `:not()` pseudo-class + - `inert` variant for `inert` attribute + - `nth-*` variants (`nth-3:`, `nth-last-5:`, `nth-of-type-4:`, `nth-last-of-type-6:`) + - `in-*` variant (like `group-*` but without adding `group` class) + - `open` variant now supports `:popover-open` + - `**` variant for targeting all descendants + +## Custom Extensions + +- **Custom utilities**: Use `@utility` directive + ```css + @utility tab-4 { + tab-size: 4; + } + ``` + +- **Custom variants**: Use `@variant` directive + ```css + @variant pointer-coarse (@media (pointer: coarse)); + @variant theme-midnight (&:where([data-theme="midnight"] *)); + ``` + +- **Plugins**: Use `@plugin` directive + ```css + @plugin "@tailwindcss/typography"; + ``` + +## Breaking Changes + +- **Removed deprecated utilities**: + - `bg-opacity-*` → Use `bg-black/50` instead + - `text-opacity-*` → Use `text-black/50` instead + - And others: `border-opacity-*`, `divide-opacity-*`, etc. + +- **Renamed utilities**: + - `shadow-sm` → `shadow-xs` (and `shadow` → `shadow-sm`) + - `drop-shadow-sm` → `drop-shadow-xs` (and `drop-shadow` → `drop-shadow-sm`) + - `blur-sm` → `blur-xs` (and `blur` → `blur-sm`) + - `rounded-sm` → `rounded-xs` (and `rounded` → `rounded-sm`) + - `outline-none` → `outline-hidden` (for the old behavior) + +- **Default style changes**: + - Default border color is now `currentColor` (was `gray-200`) + - Default `ring` width is now 1px (was 3px) + - Placeholder text now uses current color at 50% opacity (was `gray-400`) + - Hover styles only apply on devices that support hover (`@media (hover: hover)`) + +- **Syntax changes**: + - CSS variables in arbitrary values: `bg-(--brand-color)` instead of `bg-[--brand-color]` + - Stacked variants now apply left-to-right (not right-to-left) + - Use CSS variables instead of `theme()` function + +## Advanced Configuration + +- **Using a prefix**: + ```css + @import "tailwindcss" prefix(tw); + ``` + - Results in classes like `tw:flex`, `tw:bg-red-500`, `tw:hover:bg-red-600` + +- **Source detection**: + - Automatic by default (ignores `.gitignore` files and binary files) + - Add sources: `@source "../node_modules/@my-company/ui-lib";` + - Disable automatic detection: `@import "tailwindcss" source(none);` + +- **Legacy config files**: + ```css + @import "tailwindcss"; + @config "../../tailwind.config.js"; + ``` + +- **Dark mode configuration**: + ```css + @import "tailwindcss"; + @variant dark (&:where(.dark, .dark *)); + ``` + +- **Container customization**: Extend with `@utility` + ```css + @utility container { + margin-inline: auto; + padding-inline: 2rem; + } + ``` + +- **Using `@apply` in Vue/Svelte**: + ```html + + ``` \ No newline at end of file diff --git a/.cursor/rules/tanstack-rule.mdc b/.cursor/rules/tanstack-rule.mdc new file mode 100644 index 0000000..9e1791f --- /dev/null +++ b/.cursor/rules/tanstack-rule.mdc @@ -0,0 +1,11 @@ +--- +description: +globs: +alwaysApply: true +--- +--- +description: General rules for Tanstack Start. +globs: **/*.{ts,tsx,js,jsx} +--- +- If you try to import a Link use import { Link } from "@tanstack/react-router" not import { Link } from "@tanstack/react-router" +- No need to import import * as React from "react" \ No newline at end of file diff --git a/.cursor/rules/typescript-usage-rule.mdc b/.cursor/rules/typescript-usage-rule.mdc new file mode 100644 index 0000000..e840338 --- /dev/null +++ b/.cursor/rules/typescript-usage-rule.mdc @@ -0,0 +1,13 @@ +--- +description: +globs: +alwaysApply: true +--- +--- +description: Specific guidelines for TypeScript usage, including strict typing and interface usage. +globs: **/*.{ts,tsx} +--- +- Utilize TypeScript's features to ensure type safety. +- Prefer interfaces over types when defining object shapes. +- Use generics to create reusable components and functions. +- Enforce strict typing and avoid 'any' type as much as possible. \ No newline at end of file diff --git a/.cursor/rules/ui-and-styling-rule.mdc b/.cursor/rules/ui-and-styling-rule.mdc new file mode 100644 index 0000000..131a6a3 --- /dev/null +++ b/.cursor/rules/ui-and-styling-rule.mdc @@ -0,0 +1,12 @@ +--- +description: +globs: +alwaysApply: true +--- +--- +description: Guidelines for UI and styling, focusing on Tailwind CSS and Shaden UI best practices. +globs: **/*.{ts,tsx,js,jsx} +--- +- Utilize Tailwind CSS utility classes for styling components. +- Follow Shaden UI component guidelines and best practices. +- Ensure UI is responsive and accessible. \ No newline at end of file diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..3c44241 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,9 @@ +root = true + +[*] +indent_style = space +indent_size = 4 +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = true +insert_final_newline = true diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..5e8758c --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @prisis diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..67fe8ce --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,132 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +[INSERT CONTACT METHOD]. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..9c378f3 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,748 @@ +# How to Contribute + +If you're reading this, you're awesome! +Thank you for being a part of the community and helping us make these projects great. +Here are a few guidelines that will help you along the way. + +## How do I... + +- [Use This Guide](#introduction)? +- Ask or Say Something? + - [Request Support](#request-support) + - [Report an Error or Bug](#report-an-error-or-bug) + - [Request a Feature](#request-a-feature) +- Make Something? + - [Your First Pull Request](#first-pull-request) + - [Project Setup](#project-setup) + - [Contribute Documentation](#contribute-documentation) + - [Contribute Code](#contribute-code) + - [Deprecation workflow](#deprecation-workflow) + - [Documenting changes for new major versions](#major-version-docs) + - [JSDocs](#js-docs) + - [Commit Message Guidelines](#committing) +- Manage Something + - [Provide Support on Issues](#provide-support-on-issues) + - [Label Issues](#label-issues) + - [Clean Up Issues and PRs](#clean-up-issues-and-prs) + - [Review Pull Requests](#review-pull-requests) + - [Merge Pull Requests](#merge-pull-requests) + - [Release process](#release process) + - [Join the Project Team](#join-the-project-team) + +## [Code of Conduct](https://github.com/visulima/visulima.com/blob/main/.github/CODE_OF_CONDUCT.md) + +<\**ORGANIZATIONS*uppercase\*> has adopted the [Contributor Covenant](https://www.contributor-covenant.org/) as its Code of Conduct, and we expect project participants to adhere to it. +Please read [the full text](https://github.com/visulima/visulima.com/blob/main/.github/CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated. + +## Introduction + +Thank you so much for your interest in contributing!. All types of contributions are encouraged and valued. See the [table of contents](#toc) for different ways to help and details about how this project handles them!📝 + +Please make sure to read the relevant section before making your contribution! It will make it a lot easier for us maintainers to make the most of it and smooth out the experience for all involved. 💚 + +The [Project Team](#join-the-project-team) looks forward to your contributions. 🙌🏾✨ + +## Request Support + +If you have a question about this project, how to use it, or just need clarification about something: + +- First, search the issues to see if someone else already had the same problem as you. +- If not, open an GitHub Discussion at [Q&A](https://github.com/visulima/visulima.com/discussions/categories/q-a) +- Provide as much context as you can about what you're running into. +- Provide project and platform versions (nodejs, npm, etc) you can use `npx envinfo --system --npmPackages '@visulima/*' --binaries --browsers`, depending on what seems relevant. If not, please be ready to provide that information if maintainers ask for it. + +Once it's filed: + +- Someone will try to have a response soon. +- The project team will decide if an open discussion is a bug and will transform it to an issue. +- If you or the maintainers don't respond to an issue for 30 days, the [issue will be closed](#clean-up-issues-and-prs). If you want to come back to it, reply (once, please), and we'll reopen the existing issue. Please avoid filing new issues as extensions of one you already made. + +## Report an Error or Bug + +If you run into an error or bug with the project: + +- First, search the open issues to see if someone else already reported this error or bug. +- If it's the case, add a +1 (thumb up reaction) to the issue and reply to the thread if you have something useful to add. +- If nobody submitted this error or bug, open an issue as [Bug report](https://github.com/visulima/visulima.com/issues/new?assignees=&labels=s%3A+pending+triage%2Cc%3A+bug&projects=&template=bug_report.yml) and follow the steps to create the report. + > Include _reproduction steps_ that someone else can follow to recreate the bug or error on their own. + +Once it's filed: + +- The project team will [label the issue](#label-issues). +- A team member will try to reproduce the issue with your provided steps. + If there are no repro steps or no obvious way to reproduce the issue, the team will ask you for those steps and mark the issue as `s: awaiting more info`. + Bugs with the `s: awaiting more info` tag will not be addressed until they are reproduced. +- If the team is able to reproduce the issue, it will be marked `p: 1-normal`, `p: 2-high` or `p: 3-urgent`, as well as possibly other tags (such as `has workaround`), and the issue will be left to be [implemented by someone](#contribute-code). +- If you or the maintainers don't respond to an issue for 30 days, the [issue will be closed](#clean-up-issues-and-prs). If you want to come back to it, reply (once, please), and we'll reopen the existing issue. Please avoid filing new issues as extensions of one you already made. +- `p: 2-high`, `p: 3-urgent`, `do NOT merge yet`, `good first issue` issues may be left open, depending on perceived immediacy and severity, even past the 30 day deadline. + +## Request a Feature + +If the project doesn't do something you need or want it to do: + +- First, search the open issues to see if someone else already requested that feature. +- If it's the case, add a +1 (thumb up reaction) to the initial request and reply to the thread if you have something meaningful to add. +- If nobody submitted this request, open an issue as [New feature proposal](https://github.com/visulima/visulima.com/issues/new?assignees=&labels=s%3A+pending+triage%2Cc%3A+feature%2Cs%3A+waiting+for+user+interest&projects=&template=feature_request.yml) and follow the steps to create the proposal. + +Once it's filed: + +- The project team will [label the issue](#label-issues). +- The project team will evaluate the feature request, possibly asking you more questions to understand its purpose and any relevant requirements. + If the issue is closed, the team will convey their reasoning and suggest an alternative path forward. +- If the feature request is accepted, it will be marked for implementation with `s: accepted`, which can then be done by either by a core team member or by anyone in the community who wants to [contribute code](#contribute-code). + +Note: The team is unlikely to be able to accept every single feature request that is filed. Please understand if they need to say no. + +## Your First Pull Request + +Working on your first Pull Request? You can learn how from this free video series: + +[How to Contribute to an Open Source Project on GitHub](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github) + +To help you get your feet wet and get you familiar with our contribution process, we have a list of [good first issues](https://github.com/visulima/visulima.com/issues?q=is:open+is:issue+label:%22good+first+issue%22) that contain bugs that have a relatively limited scope. +This is a great place to get started. + +If you decide to fix an issue, please be sure to check the comment thread in case somebody is already working on a fix. +If nobody is working on it at the moment, please leave a comment stating that you intend to work on it so other people don’t accidentally duplicate your effort. + +If somebody claims an issue but doesn't follow up after more than a week, it's fine to take over, but you should still leave a comment. +If there has been no activity on the issue for 7 to 14 days, then it's safe to assume that nobody is working on it. + +## Project Setup + +So you want to contribute some code! That's great! This project uses GitHub Pull Requests to manage contributions, so [read up on how to fork a GitHub project and file a PR](https://guides.github.com/activities/forking) if you've never done it before. + +If this seems like a lot, or you aren't able to do all this setup, you might also be able to [edit the files directly](https://help.github.com/articles/editing-files-in-another-user-s-repository/) without having to do any of this setup. Yes, [even code](#contribute-code). + +If you want to go the usual route and run the project locally, though: + +- [Install Node.js](https://nodejs.org/en/download/) +- [Install nvm](https://github.com/nvm-sh/nvm#installing-and-updating) (optional) + > Visulima use nvm to manage the different node version, if you don't want to install `nvm`, check the package.json -> engines -> node value for the min support node version. +- [Install pnpm](https://pnpm.io/installation) +- [Fork the project](https://guides.github.com/activities/forking/#fork) + +Then in your terminal: + +- `cd path/to/your/clone` +- `pnpm install` +- `pnpm run build:packages` +- `pnpm run test` (optional) + +And you should be ready to go! + +> If you run into any issue with the setup, check first the [TROUBLESHOOT.md](https://github.com/visulima/visulima.com/blob/main/.github/TROUBLESHOOT.md) + +## Contribute Documentation + +Documentation is a super important, critical part of this project. Docs are how we keep track of what we're doing, how, and why. It's how we stay on the same page about our policies. And it's how we tell others everything they need in order to be able to use this project -- or contribute to it. So thank you in advance. + +Documentation contributions of any size are welcome! Feel free to file a PR even if you're just rewording a sentence to be more clear, or fixing a spelling mistake! + +To contribute documentation: + +- [Set up the project](#project-setup). +- Edit or add any relevant documentation. +- Make sure your changes are formatted correctly and consistently with the rest of the documentation. +- Re-read what you wrote, and run a spellchecker on it to make sure you didn't miss anything. +- Write clear, concise commit message(s) using [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/). Documentation commits should use `docs(): `, visit the [Committing](#committing) section for more information. +- Go to https://github.com/<**ORGANIZATIONS**>/<**REPOSITORY_NAME**>/pulls and open a new pull request with your changes. +- If your PR is connected to an open issue, add a line in your PR's description that says `Fixes: #123`, where `#123` is the number of the issue you're fixing. + +Once you've filed the PR: + +- One or more maintainers will use GitHub's review feature to review your PR. +- If the maintainer asks for any changes, edit your changes, push, and ask for another review. +- If the maintainer decides to pass on your PR, they will thank you for the contribution and explain why they won't be accepting the changes. That's ok! We still really appreciate you taking the time to do it, and we don't take that lightly. 💚 +- If your PR gets accepted, it will be marked as such, and merged into the `main` branch soon after. + Your contribution will be distributed to the masses with our [release process](#release-process). + +## Contribute Code + +### Important + +> By contributing code to this project, you: +> +> - Agree that you have authored 100% of the content +> - Agree that you have the necessary rights to the content +> - Agree that you have received the necessary permissions from your employer to make the contributions (if applicable) +> - Agree that the content you contribute may be provided under the Project license(s) +> - Agree that, if you did not author 100% of the content, the appropriate licenses and copyrights have been added along with any other necessary attribution. + +We like code commits a lot! They're super handy, and they keep the project going and doing the work it needs to do to be useful to others. + +Code contributions of just about any size are acceptable! + +The main difference between code contributions and documentation contributions is that contributing code requires inclusion of relevant tests for the code being added or changed. Contributions without accompanying tests will be held off until a test is added, unless the maintainers consider the specific tests to be either impossible, or way too much of a burden for such a contribution. + +To contribute code: + +- [Set up the project](#project-setup). +- Make any necessary changes to the source code. +- Include any [additional documentation](#contribute-documentation) the changes might need. +- Write tests that verify that your contribution works as expected. +- Write clear, concise commit message(s) using [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/). +- Dependency updates, additions, or removals must be in individual commits, and the message must use the format: `(deps): PKG@VERSION`, where `` is any of the usual `conventional-changelog` prefixes, at your discretion. +- +- Go to https://github.com/<**ORGANIZATIONS**>/<**REPOSITORY_NAME**>/pulls and open a new pull request with your changes. +- If your PR is connected to an open issue, add a line in your PR's description that says `Fixes: #123`, where `#123` is the number of the issue you're fixing. + +Once you've filed the PR: + +- Barring special circumstances, maintainers will not review PRs until all checks pass. +- One or more maintainers will use GitHub's review feature to review your PR. +- If the maintainer asks for any changes, edit your changes, push, and ask for another review. Additional tags (such as `needs-tests`) will be added depending on the review. +- If the maintainer decides to pass on your PR, they will thank you for the contribution and explain why they won't be accepting the changes. That's ok! We still really appreciate you taking the time to do it, and we don't take that lightly. 💚 +- If your PR gets accepted, it will be marked as such, and merged into the `main` branch soon after. + Your contribution will be distributed to the masses with our [release process](#release-process). + +### Deprecation Workflow + + + +If you ever find yourself deprecating something in the source code, you can follow these steps to save yourself (and the reviewers) some trouble. + +Add a `@deprecated` parameter to the end of the JSDoc with a human-readable description message with a suitable replacement for the deprecated function. +Lastly, add a `@see` parameter to the JSDoc with a link to the replacement (if it exists). + +Example: + +```ts +/** + * @deprecated Use `new function/class` instead. + */ +``` + +### Documenting changes for new major versions + + + +Each major version has an upgrading guide `UPGRADE.md`. + +While developing new features and fixing bugs for a new release, changes are added to the migration guide to aid developers when the version is released. + +The general principle is to document anything which requires a normal user of the package to change their code, when upgrading to the new major version. + +There are two sections: + +- Breaking changes (user MUST change their code) +- Deprecations and other changes (user SHOULD change their code, but it will still work for this major version even if they don't) + +Not every change needs to be in the migration guide. If it is too long, it becomes hard for users to spot the important changes. + +### JSDocs + + + +JSDoc are comments above any code structure (variable, function, class, etc.) that begin with `/**` and end with `*/`. Multiline comments start (if not being the start or end line) with a `*`. +For more info checkout [jsdoc.app](https://jsdoc.app/about-getting-started.html). + +JSDoc will be read and automatically processed by `generate:api-docs` and therefore need to follow some project conventions. Other standards are in place because we think they increase the code quality. + +> We have a small set of JSDoc tags that all methods should have. + +- Description +- `@param` - If the method has parameters +- `@see` - If there are other important methods +- `@example` - Example calls without and with parameters, including a sample result of each call +- `@since` - The version this method was added (or is likely to be added) +- `@deprecated` - If the method is deprecated, with additional information about replacements + + + + + + + + + + +
DoDont
+ +```ts +/** + * This is a good JSDoc description for a method that generates foos. + * + * @param options The optional options to use. + * @param options.test The parameter to configure test. Defaults to `'bar'`. + * + * @see helper.fake + * + * @example + * foo() // 'foo' + * foo({ test: 'oof' }) // 'of' + * + * @since 7.5.0 + * + * @deprecated Use `random()` instead. + */ +function foo(options: { test: string } = {}): string { + // implementation +} +``` + + + +```ts +/** + * This is a bad JSDoc description. + * + * @return foo + */ +function foo(options: { test: string }) { + // implementation +} +``` + +
+ +> We use eslint-plugin-jsdoc to test for basic styling and sorting of doc-tags. + +This is in place so all JSDoc tags will get sorted automatically, so you don't have to bother with it. This also means that most rules in this section can get auto fixed by the eslint formatter. + +> JSDocs should always be multiline + +While single line JSDoc are technically valid, we decided to follow this rule since it makes changes in the git diff much more clear and easier to understand. + + + + + + + + + + +
DoDont
+ +```ts +/** + * This is a good JSDoc description. + */ +function foo() { + // implementation +} +``` + + + +```ts +/** This is a bad JSDoc description. */ +function foo() { + // implementation +} +``` + +
+ +> Everything that can be accessed directly by a user should have JSDoc. + +This rule is aimed to target anything that is exported from a package. This includes types, interfaces, functions, classes and variables. So if you introduce anything new that is not internal, write JSDoc for it. + +> If a `@param` has a default value, it needs to be mentioned at the end of the sentence. + +```ts +/** + * This is a good JSDoc description. + * + * @param bar this is a parameter description. Defaults to `0`. + */ +function foo(bar: number = 0) { + // implementation +} +``` + +> If a function can throw an error (Error) you have to include the `@throws` tag with an explanation when an error could be thrown + +```ts +/** + * This is a good JSDoc description. + * + * @param bar this is a parameter description. Defaults to `0`. + * + * @throws If bar is negative. + */ +function foo(bar: number = 0) { + // implementation +} +``` + +> Sentences should always end with a period. + +This rule ensures minimal grammatical correctness in the comments and ensures that all comments look the same. + +> Different tags have to be separated by an empty line. + +This rule improves the comments readability by grouping equivalent tags and making them more distinguishable from others. + + + + + + + + + + +
DoDont
+ +```ts +/** + * This is a good JSDoc block, because it follows the our preferences. + * + * @param bar The first argument. + * @param baz The second argument. + * + * @example foo(1, 1) // [1, 1] + * @example foo(13, 56) // [13, 56] + */ +function foo(bar: number, baz: number): [number, number] { + // implementation +} +``` + + + +```ts +/** + * This is a bad JSDoc block, because it has no linebreaks between sections. + * @param bar The first argument. + * @param baz The second argument. + * @example foo(1, 1) // [1, 1] + * @example foo(13, 56) // [13, 56] + */ +function foo(bar: number, baz: number): [number, number] { + // implementation +} +``` + +
+ +## Committing + +To ensure consistency throughout the source code, keep these rules in mind as you are working: + + + +We have very precise rules over how our Git commit messages must be formatted. +This format leads to **easier to read commit history**. + +Each commit message consists of a **header**, a **body**, and a **footer**. + +``` +
+ + + +