diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2730973fc..5120e31ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,6 +14,23 @@ Each of our docs should adhere to the following: - Graphics and images are clear and useful - Any prerequisites and next steps are defined -## Style guide +## Website contributions -TODO +We welcome contributions to improve the Tina.io experience! + +1. **Fork the Repo**: Work on your own fork to avoid conflicts. +1. **Branching**: Use `feature/your-feature-name` or `bugfix/your-bugfix-name` for changes. +1. **Using TinaCMS**: For content changes (e.g., docs), use visual editing with TinaCMS locally (e.g., http://localhost:3000/admin). +1. **Commits**: Write clear, descriptive messages. Break large changes into multiple commits. +1. **Code Quality**: + - Use Tailwind over inline CSS or styled components. + - Follow DRY principles and refactor reusable code. + - Comment on calculations or workarounds, and open issues for any technical debt. +1. **Pull Requests**: + - Reference related issues and include screenshots for UI changes. + - If no issue exists, create one and link it. + - Commit the generated `tina-lock.json` file, and rerun the project locally after merging to update it. +1. **Review Process**: + - Due to Vercel deployment issues, maintainers will recreate your changes on a new branch to test before approval. + +Cheers! 🦙 diff --git a/README.md b/README.md index effbc2a01..1b0705594 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,68 @@ -# Tina.io website +### Hi Legends 👋 +#

Tina.io – the Website for [TinaCMS](https://github.com/tinacms/tinacms)

+ +Source code for the tina.io website, including the TinaCMS documentation and blog. -Source code for the [tina.io](https://tina.io) website. +Found a bug? Create a PBI and we'll look into it. -## Development -``` +## 🧿 Vision + +Make a wesbite to communicate the awesomeness of TinaCMS. + +## 🛠️ Tech Stack + +Static web application built with... + +- [React](https://reactjs.org/) +- [Next.js](https://nextjs.org/) +- [TypeScript](https://www.typescriptlang.org/) +- [Tailwind CSS](https://tailwindcss.com/) + +for Node versions, check [this](https://tina.io/docs/setup-overview/) docs page. + +- and of course... [TinaCMS](https://github.com/tinacms/tinacms)! 🦙 + +Hosting and deployment... + +- GitHub and [Vercel](https://vercel.com/) + +
+ +## 🛠️ Dependency Installation + Setup + +We're using [pnpm](https://pnpm.io/) as the package manager for node. + +```bash cp .env.example .env pnpm i +``` + +**Note**: Python is required for gyp – install [python](https://www.python.org/downloads/) and if necessary (newer python versions) the [setup tools](https://stackoverflow.com/a/77638742). + +
+ +## 🧑🏻‍💻 Running the Project +```bash pnpm dev ``` +This will spin up the react/Next project locally, running on [localhost:3000](http://localhost:3000) (react app) and [localhost:4001](http://localhost:4001/graphql) (playground for testing graphql against the Tina datalayer). -## Vision -Make a wesbite to communicate the awesomeness of TinaCMS +
-## Tech Stack -- NextJS -- TinaCMS -- GitHub -- Markdown +## Not Familiar with Tina? +We've put together a simple explanation of the project directory – in [_docs/Directory-Structure](_docs/Directory-Structure.md). -### Testing Local TinaCMS Changes +This should give you an idea of how it all fits into the project. -If you have the **tinacms** repository cloned locally you can use it when running **tina.io**: +Additionally, the Tina [docs](https://tina.io/docs/) contains the usage details for development with Tina. -``` -TINA=../path/to/tinacms pnpm dev -``` +
-You can also specify which packages you want to watch: +## Additional Documentation -``` -TINA=../path/to/tinacms TINA_WATCH=@tinacms/forms,react-tinacms-inline -``` +- [Definition of Done (work requirements)](/_docs/Definition-of-Done.md) +- [Definition of Ready (PBI requrements)](/_docs/Definition-of-Ready.md) +- [Contribution Guidelines](CONTRIBUTING.md) -> ### Warning -> -> This will only work for packages loaded by webpack. That means that environments which don't use -> webpack (i.e. SSR builds) will not use this alias. diff --git a/_docs/Definition-of-Done.md b/_docs/Definition-of-Done.md new file mode 100644 index 000000000..532f8fc09 --- /dev/null +++ b/_docs/Definition-of-Done.md @@ -0,0 +1,23 @@ +# Definition Of Done + +An issue in this repository can be closed (considered done) for... + +### Code + Content Changes + +1. Code compiles and the change aligns with the issue description. All tasks related to the issue have been completed. +1. When the latest commit has been manually tested against a preview deployment. +1. The code has been reviewed and approved by a project maintainer. + +1. Code has been deployed to production. +1. Any bugs or technical debt that arise from the issue have been logged in a PBI that links to this code change. +1. Issue had been closed with a closing comment added describing solution or linking changed pages. +1. All relevant automated tests have been executed and passed. + + +### Other Tasks + +1. All issue tasks have been ticked. + +1. PO has signed off on the task. +1. Issue had been closed with a closing comment added describing solution or last status. +1. Done email has been sent (if required). \ No newline at end of file diff --git a/_docs/Definition-of-Ready.md b/_docs/Definition-of-Ready.md new file mode 100644 index 000000000..3cc5208c0 --- /dev/null +++ b/_docs/Definition-of-Ready.md @@ -0,0 +1,10 @@ +# Definition Of Ready + +Prior to being actioned, an issue in this repository should at minimum contain... + +- Enough detail for the team (or future teams) to action +- Effort assigned (we use the [SSW recomendation](https://www.ssw.com.au/rules/estimating-do-you-know-how-to-size-user-stories-effectively/) for business and effort value estimates). + + ...possible efforts are 0, 1, 2, 4, 8, 16 with each point of effort corresponding to a quarter day (~2 hours). Larger tasks should be done over multiple PBIs. +- We're not using business values for this project. +- Assigned to `backlog ready` with PO approval. \ No newline at end of file diff --git a/_docs/Directory-Structure.md b/_docs/Directory-Structure.md new file mode 100644 index 000000000..ccf8e47ad --- /dev/null +++ b/_docs/Directory-Structure.md @@ -0,0 +1,50 @@ +# 🏗️ Directory Structure + +Last updated: 26/09/2024 + +``` +. +├── components/ +│ ├── DocumentNavigation/ +│ │ └── ... various navigation menu components for the docs +│ ├── layout/ +│ │ └── ... wrappers for site pages +│ ├── blocks/ +│ │ ├── ... Tina block-editing components and schemas +│ │ └── ... 🦙 https://tina.io/docs/editing/blocks/ 🦙 +│ ├── tinaMarkdownComponents/ +│ │ ├── ... Rich-Text styling and embedded components +│ │ └── ... 🦙 https://tina.io/docs/editing/markdown/ 🦙 +│ ├── toc/ +│ │ ├── ... contains docs table of contents (toc) schema +│ │ └── ... generated toc component from doc headings +│ ├── ui/ +│ │ └── ... re-usable utility components +│ ├── styles/ +│ │ └── ... mix of styling code, TODO: standardise this +│ └── ➕ +├── content/ +│ └── ... 🦙 🦙 🦙 (tina-managed site content) +├── data-api/ and indices/ +│ └── ... related to algolia and content searching +├── pages/ +│ └── ... 🖥️ nextjs page router 🖥️ +├── public/ +│ └── ... assets +├── rss/ +│ └── ... rss generation (SEO or other reasons) +├── scripts/ +│ ├── content-auditor/ +│ │ ├── ... local AI audit script for /content +│ │ └── ... 🦙 https://ollama.com/ - unafilliated llama related software 🦙 +│ └── ➕ +├── styles/ (tailwind config) +├── tina/ +│ ├── collectionsSchema/ +│ │ ├── ... Tina schema definitions (other than block templates) +│ │ └── ... 🦙 https://tina.io/docs/reference/schema/ 🦙 +│ └── ➕ +├── utils/ +│ └── ... function definitions +└── ... project config +``` \ No newline at end of file diff --git a/components/DocumentationNavigation/DocsHeaderNav.tsx b/components/DocumentationNavigation/DocsHeaderNav.tsx index cad6d3999..3d4fa5d3d 100644 --- a/components/DocumentationNavigation/DocsHeaderNav.tsx +++ b/components/DocumentationNavigation/DocsHeaderNav.tsx @@ -1,7 +1,7 @@ import React from 'react' +import data from '../../content/docs-navigation.json' import { LinkButton } from '../ui' import { DynamicLink } from '../ui/DynamicLink' -import data from '../../content/docs-navigation.json' export const DocsHeaderNav = () => { return (