refactor: improve guides

CONTRIBUTING.md

@@ -1,125 +1,66 @@
 # Contributing
 
-When contributing to this repository, please first discuss the change you wish
-to make via issue, email, or any other method with the owners of this
-repository before making a change.
+When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.
 
-Please note we have a [Code of Conduct](CODE_OF_CONDUCT.md), please follow it
-in all your interactions with the project.
+Please note we have a [Code of Conduct](CODE_OF_CONDUCT.md), please follow it in all your interactions with the project.
 
-# Contributing to the blog
+If this is your first contribution to an open-source project on GitHub have a look at the [GitHub Docs](https://docs.github.com/en) specially the [Contributing to Projects](https://docs.github.com/en/get-started/quickstart/contributing-to-projects?tool=webui) guide.
 
-First of all, thank you for wanting to contribute for our blog 👍. This section contains all the information you need to know to contribute to our blog page. Should you have any questions, feel free to contact us and we will try our best in answering them.
+### Blog
 
-## Before writing
+If you whish to write for the blog please read the [Blog Contributing Guide](apps/blog/CONTRIBUTING.md).
 
-### Cloning and creating a new branch
+## How To Contribute
 
-If you have decided to contribute to our blog, the first thing you need to do is clone the repository and creating a new branch where you will be writing our post. In other words, you should run the following commands:
+#### Branching Convention
 
-```
-git clone https://github.com/coderdojobraga/shuriken.git
-cd shuriken
-git switch -c your-branch-name
-```
-
-where `your-branch-name` should be your initials (first letter of the your first and last name) folowed by `/blog/your-post-topic` . For example, if your name is João Silva and you are writing about how to make an hello world in python, your branch name would be something like `js/blog/python-hello-world`.
-
-In alternative, you can run our `create-blog-post.sh` script like
-
-```
-sh create-blog-post.sh your-branch-name your-blog-post-name
-```
+Your branch name should be your initials (first letter of the your first and last name) folowed by `/contribution-subject`. For example, if your name is Rui Lopes and you are fixing a logo alignment, your branch name would be something like `rl/fix-logo`.
 
-### Note for those not a part of the Coderdojo Braga team
+#### Security Bug Reports
 
-If you are not a member of our team on Github, then instead of creating a branch you need to fork this project. If you don't know how to do that, please [refer to this guide](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
+If you encounter a security bug, please message us. **_Do not open an issue_**.
 
-## Bug reports
+## Developing
 
-If you encounter a bug during writing, please message us. **_Do not open an issue_**. If it is something important it will be fixed. Or, if you have the time, you can try and fix it for us 😀.
+### Build
 
-## Opening a PR
-
-After you are done writing, commit your changes to your branch and push.
+To build all apps and packages, run the following command:
 
 ```
-git add *your changed files*
-git commit -m "Your commit message"
-git push
+npm run build
 ```
 
-Now all that is left to do is opening a Pull Request so your post can be published. If you don't know how to open a Pull Request, please refer to [this guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). **_Don't forget to select the reviewers_**. At least, you should put [Filipe Felício](https://github.com/feliciofilipe) and [Rui Oliveira](https://github.com/ruioliveira02).
-Once your PR is approved, your blog will be pushed to main and to production. Congratulations, you just contributed to the CoderDojo Braga's blog 👍.
-
-## Previewing your work
-
-To preview your amazing work, run shuriken (`npm run dev`) and open your page. It should be in http://localhost:3000/posts/your-post-name.
-
-# Contributing to the blog
-
-First of all, thank you for wanting to contribute for our blog 👍. This section contains all the information you need to know to contribute to our blog page. Should you have any questions, feel free to contact us and we will try our best in answering them.
-
-## Before writing
+### Develop
 
-### Creating the markdown file
-
-If you don't know already, our blog is a collection of Markdown files. So, in order to write your own post, you must first create a .md file. To create the file, navigate to the posts directory `content/blog `and create your file.
+To develop all apps and packages, run the following command:
 
 ```
-cd content/blog
-touch your-post-name.md
+npm run dev
 ```
 
-Now you can just open your favorite editor and start writing.
-
-#### File name
-
-The name of your file should be the same as the branch you created. So, João, in the previous example, would have to create a file named `python-hello-world.md`. All initials should be lowercase letters and words should be separated by a `-`.
-
-## During writing
+### Remote Caching
 
-### Meta data
+Turborepo can use a technique known as [Remote Caching](https://turborepo.org/docs/core-concepts/remote-caching) to share cache artifacts across machines, enabling you to share build caches with your team and CI/CD pipelines.
 
-The first part of your file should be metadata used by the website to correctly display your post. Currently, it should look like this:
+By default, Turborepo will cache locally. To enable Remote Caching you will need an account with Vercel. If you don't have an account you can [create one](https://vercel.com/signup), then enter the following commands:
 
 ```
----
-title: "Your title"
-date: "Publishing date"
-author: "your name"
-photo: "path to your image"
-draft: true/false
-featured: true/false
----
+cd my-turborepo
+npx turbo login
 ```
 
-The date should be in the `yyyy-mm-dd`format, and you should set it to a few days after you intend on creating a PR (if you don't know what that means, read to the end). Your image should be under `../img/team/`. If you don't have an image yet, upload one to that directory and include it in your branch. So, your `photo` should look like `../img/team/your-photo.format`. If you aren't done writing, set the `draft`property to `true`.
-
-If your post is very relevant it should be featured on our main page. If that is the case, set the `feature` to true. However, always consult with the dev team on whether or not your post should be featured before setting that property.
-
-### Markdown Support
-
-Currently not all of Markdown features are supported. Here is a list of all important nuances you should take into account when writing:
+This will authenticate the Turborepo CLI with your [Vercel account](https://vercel.com/docs/concepts/personal-accounts/overview).
 
-- Inline code is not supported, _yet_
-- If you want to use emojis, you have to use the corresponding [HTML character](https://www.w3schools.com/charsets/ref_emoji.asp)
-- Headings are only supported until 3 `#`
-- Superscript and subscript are not supported
-
-### Previewing your work
-
-To preview your amazing work, run shuriken (`npm run dev`) and open your page. It should be in http://localhost:3000/blogPosts/your-post-name.
-
-## After writing
-
-After you are done writing, commit your changes to your branch and push.
+Next, you can link your Turborepo to your Remote Cache by running the following command from the root of your turborepo:
 
 ```
-git add content/blog/your-post-name.md
-git commit -m "Your commit message"
-git push
+npx turbo link
 ```
 
-Now all that is left to do is opening a Pull Request so your post can be published. If you don't know how to open a Pull Request, please refer to [this guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). **_Don't forget to select the reviewers_**. At least, you should put [Filipe Felício](https://github.com/feliciofilipe) and [Rui Oliveira](https://github.com/ruioliveira02).
-Once your PR is approved, your blog will be pushed to main and to production. Congratulations, you just contributed to the CoderDojo Braga's blog 👍.
+## 🔗 References
+
+You can use these resources to learn more about the technologies this project
+uses.
+
+- [Getting Started with npm](https://docs.npmjs.com/getting-started)
+- [Turborepo Quickstart](https://turbo.build/repo/docs)

README.md

@@ -1,6 +1,24 @@
-# Shuriken
-
-## What's inside?
+<h1 align="center">shuriken</h1>
+<div align="center">
+  <img height="120" src="apps/app/public/koi/star.png" />
+</div>
+<br />
+<div align="center">
+  <strong>
+    Frontend platform for managing session registrations and recording ninjas' progress
+  </strong>
+</div>
+<br />
+<div align="center">
+
+  [![Actions Status](https://github.com/coderdojobraga/shuriken/workflows/CI/badge.svg)](https://github.com/coderdojobraga/shuriken/actions)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+  ![GitHub contributors](https://img.shields.io/github/contributors-anon/coderdojobraga/shuriken)
+  ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/coderdojobraga/shuriken)
+
+</div>
+
+## 🗃️ What's Inside?
 
 This turborepo uses [npm](https://www.npmjs.com/) as a package manager. It includes the following packages/apps:
 
@@ -26,6 +44,8 @@ This turborepo has some additional tools already setup for you:
 - [ESLint](https://eslint.org/) for code linting
 - [Prettier](https://prettier.io) for code formatting
 
+## 💻 Developing
+
 ### Build
 
 To build all apps and packages, run the following command:
@@ -60,8 +80,17 @@ Next, you can link your Turborepo to your Remote Cache by running the following
 ```
 npx turbo link
 ```
+## 🤝 Contributing
+
+When contributing to this repository, please first discuss the change you wish to make via discussions, issues, email, or any other method with the owners of this repository.
+
+Please note we have a [Code of Conduct](CODE_OF_CONDUCT.md), please follow it in all your interactions with the project.
+
+We have a [Contributing Guide](CONTRIBUTING.md) to help you getting started.
+
+If you want to write for our blog we also have a [Blog Contributing Guide](apps/blog/CONTRIBUTING.md).
 
-## Useful Links
+## 🔗 Useful Links
 
 Learn more about the power of Turborepo:
 

apps/blog/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing to the blog
+
+First of all, thank you for wanting to contribute for our blog 👍. This section contains all the information you need to know to contribute to our blog page. Should you have any questions, feel free to contact us and we will try our best in answering them.
+
+## Before writing
+
+### Cloning and creating a new branch
+
+If you have decided to contribute to our blog, the first thing you need to do is clone the repository and creating a new branch where you will be writing our post. In other words, you should run the following commands:
+
+```
+git clone https://github.com/coderdojobraga/shuriken.git
+cd shuriken
+git switch -c your-branch-name
+```
+
+where `your-branch-name` should be your initials (first letter of the your first and last name) folowed by `/blog/your-post-topic` . For example, if your name is João Silva and you are writing about how to make an hello world in python, your branch name would be something like `js/blog/python-hello-world`.
+
+In alternative, you can run our `create-blog-post.sh` script like
+
+```
+sh create-blog-post.sh your-branch-name your-blog-post-name
+```
+
+#### Note for those not a part of the Coderdojo Braga team
+
+If you are not a member of our team on Github, then instead of creating a branch you need to fork this project. If you don't know how to do that, please [refer to this guide](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
+
+
+### Creating the markdown file
+
+If you don't know already, our blog is a collection of Markdown files. So, in order to write your own post, you must first create a .md file. To create the file, navigate to the posts directory `content/blog `and create your file.
+
+```
+cd content/blog
+touch your-post-name.md
+```
+
+Now you can just open your favorite editor and start writing.
+
+#### File name
+
+The name of your file should be the same as the branch you created. So, "João", from the previous example, would have to create a file named `python-hello-world.md`. All initials should be lowercase letters and words should be separated by a `-`.
+
+## During writing
+
+### Meta data
+
+The first part of your file should be metadata used by the website to correctly display your post. Currently, it should look like this:
+
+```
+---
+title: "Your title"
+date: "Publishing date"
+author: "your name"
+photo: "path to your image"
+draft: true/false
+featured: true/false
+---
+```
+
+The date should be in the `yyyy-mm-dd`format, and you should set it to a few days after you intend on creating a PR (if you don't know what that means, read to the end). Your image should be under `../img/team/`. If you don't have an image yet, upload one to that directory and include it in your branch. So, your `photo` should look like `../img/team/your-photo.format`. If you aren't done writing, set the `draft`property to `true`.
+
+If your post is very relevant it should be featured on our main page. If that is the case, set the `feature` to true. However, always consult with the dev team on whether or not your post should be featured before setting that property.
+
+### Markdown Support
+
+Currently not all of Markdown features are supported. Here is a list of all important nuances you should take into account when writing:
+
+- Inline code is not supported, _yet_
+- If you want to use emojis, you have to use the corresponding [HTML character](https://www.w3schools.com/charsets/ref_emoji.asp)
+- Headings are only supported until 3 `#`
+- Superscript and subscript are not supported
+
+## After writing
+
+### Previewing your work
+
+To preview your amazing work, run shuriken (`npm run dev`) and open your page. It should be in http://localhost:3001/posts/your-post-name.
+
+### Submitting you work
+
+After you are done writing, commit your changes to your branch and push.
+
+```
+git add content/blog/your-post-name.md
+git commit -m "Your commit message"
+git push
+```
+
+Now all that is left to do is opening a Pull Request so your post can be published. If you don't know how to open a Pull Request, please refer to [this guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). **_Don't forget to select the reviewers_**. At least, you should put [Filipe Felício](https://github.com/feliciofilipe) and [Rui Oliveira](https://github.com/ruioliveira02).
+Once your PR is approved, your blog will be pushed to main and to production. Congratulations, you just contributed to the CoderDojo Braga's blog 👍.

apps/blog/README.md

@@ -1,30 +1,7 @@
-## Getting Started
+# CoderDojo Braga Blog
 
-First, run the development server:
+This is our [Blog](https://blog.coderdojobraga.org/)!
 
-```bash
-yarn dev
-```
+## Writing For The Blog
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
-
-You can start editing the page by modifying `pages/index.js`. The page auto-updates as you edit the file.
-
-[API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.js`.
-
-The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages.
-
-## Learn More
-
-To learn more about Next.js, take a look at the following resources:
-
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
-
-## Deploy on Vercel
-
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_source=github.com&utm_medium=referral&utm_campaign=turborepo-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+If you whish to write for the blog please read the [Blog Contributing Guide](apps/blog/CONTRIBUTING.md).