Skip to content

Connect, collaborate, and grow with a community of TypeScript developers

docs: Updates README.md and CONTRIBUTING.md (#396)

Jim Burbridged6dc9d31ab68
diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
new file mode 100644
index 00000000..c899a2f5
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug.yml
@@ -0,0 +1,42 @@
+name: Bug Report
+description: File a bug report
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for taking the time to fill out this bug report!
+ - type: textarea
+ id: what-happened
+ attributes:
+ label: What happened?
+ description: Also tell us, what did you expect to happen?
+ placeholder: Tell us what you see!
+ value: "A bug happened!"
+ validations:
+ required: true
+ - type: dropdown
+ id: browsers
+ attributes:
+ label: What browsers are you seeing the problem on?
+ multiple: true
+ options:
+ - Firefox
+ - Chrome
+ - Safari
+ - Microsoft Edge
+ - type: textarea
+ id: logs
+ attributes:
+ label: Relevant log output
+ description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+ render: zsh
+ - type: checkboxes
+ id: terms
+ attributes:
+ label: Code of Conduct
+ description: By submitting this issue, you agree to follow our [Code of Conduct](https://typehero.dev/code_of_conduct)
+ options:
+ - label: I agree to follow this project's Code of Conduct
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml
new file mode 100644
index 00000000..361c58b0
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature.yml
@@ -0,0 +1,32 @@
+name: Feature
+description: An enhancement or feature
+title: "[Feature]: "
+labels: ["enhancement", "triage"]
+body:
+ - type: textarea
+ id: description
+ attributes:
+ label: Description
+ description: A step-by-step description of the suggested feature/enhancement.
+ placeholder: On the user page, you should be able to...
+ validations:
+ required: true
+ - type: markdown
+ attributes:
+ value: >
+ | Please include any screenshots which would help demonstrate the steps
+ and point out which parts the feature is related to
+ - type: textarea
+ id: explanation
+ attributes:
+ label: Explanation
+ description: Why would this be useful to most CONTRIBUTING.md users. You may also want to point out other projects that have solved a similar feature.
+ placeholder: Leetcode does this thing on this page...
+ - type: checkboxes
+ id: terms
+ attributes:
+ label: Code of Conduct
+ description: By submitting this issue, you agree to follow our [Code of Conduct](https://typehero.dev/code_of_conduct)
+ options:
+ - label: I agree to follow this project's Code of Conduct
+ required: true
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 00000000..7905fc5a
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,87 @@
+# Contributor Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and
+expression, level of experience, education, socio-economic status, nationality,
+personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Attempting collaboration before conflict
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- Violence, threats of violence, or inciting others to commit self-harm
+- The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+- Trolling, intentionally spreading misinformation, insulting/derogatory
+ comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+- Abuse of the reporting process to intentionally harass or exclude others
+- Advocating for, or encouraging, any of the above behavior
+- Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers 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, or to ban temporarily or permanently any
+contributor for other behaviors that they deem inappropriate, threatening,
+offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting us anonymously through
+[the discord](https://discord.gg/trashdev). All complaints will be
+reviewed and investigated and will result in a response that is deemed necessary
+and appropriate to the circumstances. The project team is obligated to maintain
+confidentiality with regard to the reporter of an incident.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+If you are unsure whether an incident is a violation, or whether the space where
+the incident took place is covered by our Code of Conduct, **we encourage you to
+still report it**. We would prefer to have a few extra reports where we decide
+to take no action, than to leave an incident go unnoticed and unresolved that
+may result in an individual or group to feel like they can no longer participate
+in the community. Reports deemed as not a violation will also allow us to
+improve our Code of Conduct and processes surrounding it. If you witness a
+dangerous situation or someone in distress, we encourage you to report even if
+you are only an observer.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org/),
+[version 1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cd128293..b5928861 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,109 +1,124 @@
-## Contributing
+# Contributing
-To contribute you will first need to fork the repo and make some adjustments to get it up and running on your local
-machine. Below are the steps to follow in order for you to get dotfyle to run on your local machine.
-
-### 1. Create a `.env` file
-
-```
-cp .env.example .env
-```
-
-Provide your own values as needed.
-
-### 2 Configure your database
-
-You can either use planetscale or a local docker container to run your database.
-Use either 2.a or 2.b for the next step.
-
-### 2.a Docker local DB
-
-Starting the docker container
-
-```
-docker compose up -d
-```
-
-### 2.b Planetscale cloud DB
-
-[Follow the planetscale quick start guide to get you connection string][planetscale-quick-start]
-
-1. Click Get Started -> Continue with GitHub
-2. Click Blue "create".
- <br/><img width="444" alt="Screenshot 2023-06-30 at 3 44 27 PM" src="https://github.com/bautistaaa/typehero/assets/31113245/c30929fe-68ca-407d-9894-ef2ea52ced3c">
-
-3. Click "Get connection strings".
- <br/><img width="429" alt="Screenshot 2023-06-30 at 3 46 45 PM" src="https://github.com/bautistaaa/typehero/assets/31113245/c06a5829-92e6-417f-a5e6-083b7690923f">
-
-4. Switch to "Connect with Prisma" and copy the `DATABASE_URL` for `.env` (replace **\*\*\*** with password)
- <br/><img width="344" alt="Screenshot 2023-06-30 at 3 49 03 PM" src="https://github.com/bautistaaa/typehero/assets/31113245/4c9694ef-b954-47a8-9954-c2b677a1123a">
-
-### 3. Create a new GitHub OAuth Application
-
-[Follow this link][new-oauth] to create a new app filling the following required details on creation:
-
-```
-Homepage URL: http://localhost:3000
-Authorization callback URL: http://localhost:3000/api/auth/callback/github
-```
-
-Once completed, you will be redirected to the application page settings, from there create the client secret by clicking
-on `Generate a new client secret` button.
-
-Next, copy the client secret generated and the client ID into the `.env` file, replacing `<client_id>` and
-`<client_secret>`, respectively:
-
-```
-GITHUB_ID=<client_id>
-GITHUB_SECRET=<client_secret>
-```
-
-### 4. Setup uploadthing for file uploads
-
-Go to [uploadthing.com](https://uploadthing.com/dashboard) and create a project, then copy in the secrets into your `.env`.
-
-### 5. Install dependencies
-
-Use `pnpm` to install dependencies.
-
-```
-pnpm install
-```
-
-### 6. Push Database Schema and Seed
-
-```
-pnpm db:push
-pnpm db:seed
-```
-
-### Running the dev server
-
-Finally, you can run the dev server:
-
-```
-pnpm dev
-```
-
-### Sync data
-
-Once the server is running you can seed and sync data
-
-1. Navigate to [http://localhost:5173/api/auth/github](http://localhost:5173/api/auth/github) to authenticate with GitHub OAuth.
-
-#### Tips
-
-If you ever need to blow away everything in your data and reseed run:
-
-```
-pnpm refresh
-```
-
-If you want to see if your PR will pass GitHub Checks before you push, run `pn checks`. You may also run `pn checks:fix` to let Prettier and ESLint automatically fix any issues that they can.
-
-[planetscale-quick-start]: https://planetscale.com/docs/tutorials/planetscale-quick-start-guide
-[new-oauth]: https://github.com/settings/applications/new
-
-#### Dependencies
-
-UI Library: [shadcn](https://ui.shadcn.com/)
+[![Join the Trash Discord](https://discordapp.com/api/guilds/796594544980000808/widget.png?style=banner2)][trash-discord]
+
+Thank you for considering contributing to TypeHero. As an open sourced project
+we only exist by contributions from users like you.
+
+To contribute you will first need to fork the repo. To get the repository up and
+running, please look at [LOCAL.md](/LOCAL.MD) for setup instructions.
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by the
+[CONTRIBUTING.md Code of Conduct](blob/master/CODE_OF_CONDUCT.md). By
+participating you are expected to uphold this code. Please report unacceptable
+behavior to <[email protected]>
+
+## I Want to Contribute
+
+> ### Legal Notice
+>
+> When contributing to this project, you must agree that you have authored 100%
+> of the content, that you have the necessary rights to the content and that the
+> content you contribute may be provided under the project's license.
+
+### Reporting Bugs
+
+#### Before Submitting a Bug Report
+
+A good bug report shouldn't leave others needing to chase you up for more
+information. Therefore, we ask you to investigate carefully, collect
+information, and describe the issue in detail _in your report_. Following the
+bug issue template should prompt you for any information we may need, but feel
+free to include any information you feel is relevant to the bug.
+
+#### How do I Submit a Good Bug Report?
+
+> ### You must never report security related issues, vulnerabilities, or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead, sensitive bugs must be sent by email to [[email protected]](mailto:[email protected])
+
+We use GitHub issues to track bugs and errors. If you run into an issue with the
+project:
+
+- Open an [Issue](/issues/new).
+- Explain the behavior you would expect and the actual behavior.
+- Please provide as much context as possible and describe the _reproduction
+ steps_ that someone else can follow to recreate the issue on their own. This
+ usually includes your code. For good bug reports you should isolate the
+ problem and create a reduced test case.
+- Provide the information you collected in the previous section.
+
+Once it is filed:
+
+- The project team will label that issue accordingly.
+- A team member will try to reproduce the issue with your provided steps. If
+ there are no reproduction steps or no obvious way to reproduce the issue, the
+ team will ask you for those steps and mark the issue as `needs-repro`. Bugs
+ with the `needs-repro` tag will not be addressed until they are reproduced.
+- If the team is able to reproduce the issue, it will be marked as `needs-fix`,
+ as well as possibly other tags (such as `critical`), and the issue will be
+ left to be [implemented by someone](#your-first-code-contribution)
+
+### Suggestiong Enhancements
+
+This section guides you through submitting an enhancement suggestion for
+CONTRIBUTING.md **including completely new features and minor improvements to
+existing functionality**. Following these guidelines will help maintainers and
+the community to understand your suggestion and find related suggestions.
+
+#### Before Submitting an Enhancement
+
+- Make sure that you are using the latest version.
+- Perform a search in [GitHub](/issues), or the
+ [Suggestions Channel](https://discord.com/channels/796594544980000808/1143947327892103188)
+ on Discord to see if the enhancement has already been suggested. If it has,
+ add a comment to the existing issue instead of opening a new one.
+- Find out whether your idea fits with the scope and aims of the project. It's
+ up to you to make a strong case to convince the project's developers of the
+ merits of this feature. Keep in mind that we want features that will be useful
+ to the majority of our users and not just a small subset.
+
+#### How Do I Submit a Good Enhancement Suggestion?
+
+Enhancement suggestions are tracked as [GitHub issues](/issues).
+
+- Use a **clear and descriptive title** for the issue to indentify the
+ suggestion.
+- Provide a **step-by-step description of the suggested enhancement** in as much
+ detail as possible.
+- **Describe the current behavior** and **explain which behavior you expected to
+ see instead** and why. At this point you can also tell which alternatives do
+ not work for you.
+- You may want to include **screenshots** which help you demonstrate the steps
+ or point out the part which the suggestion is related to.
+- Explain why this enhancement would be useful to most CONTRIBUTING.md users.
+ You may also want to point out the other projects which have solved a similar
+ issues.
+
+### Your First Code Contribution
+
+1. Choose an issue from the [GitHub issues](/issues), ask a member of the team
+ to assign the issue to you.
+2. Fork the repository
+3. Create a branch on your fork. You should either add in the GitHub issue
+ number to the branch name, e.g. `382_adds-in-new-thing` or ensure that the
+ issue is referenced in the Pull Request or commit message.
+4. We do not enforce a commit style like
+ [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), but
+ you are welcome to use one so long as the summary line accurately describes
+ the overall purpose of the work and the ticket is referenced either in the PR
+ or the body of the commit message. See [Commits](#commits) for example
+ commits.
+5. When ready, put up a PR that links from your fork.
+
+## References
+
+### Commits
+
+| ✅ Good | ❌ Bad |
+| :-------------------------------------------------------------------- | :--------------- |
+| Adds in [Cool New Feature Name] | YOOOOOO |
+| fix: Stops a bug on challenge pages causing tests to fail incorrectly | fixing the thing |
+| Updates caching strategy to revalidate based on hash key | Trust me bro |
+
+[trash-discord]: https://discord.gg/trashdev
diff --git a/LOCAL.md b/LOCAL.md
new file mode 100644
index 00000000..0bbc7107
--- /dev/null
+++ b/LOCAL.md
@@ -0,0 +1,165 @@
+# Local Setup
+
+[![Join the Trash Discord](https://discordapp.com/api/guilds/796594544980000808/widget.png?style=banner2)][trash-discord]
+
+[trash-discord]: https://discord.gg/trashdev
+
+To contribute you will first need to fork the repo and make some adjustments to
+get it up and running on your local machine. Below are the steps to follow in
+order for you to get TypeHero to run on your local machine.
+
+### 1. Create a `.env` file
+
+```
+cp .env.example .env
+```
+
+Provide your own values as needed.
+
+### 2 Configure your database
+
+You can either use planetscale or a local docker container to run your database.
+Use either 2.a or 2.b for the next step.
+
+### 2.a Docker local DB
+
+Starting the docker container
+
+```
+docker compose up -d
+```
+
+### 2.b Planetscale cloud DB
+
+[Follow the planetscale quick start guide to get you connection string][planetscale-quick-start]
+
+1. Click Get Started -> Continue with GitHub
+2. Click Blue "create".
+ <br/><img width="444" alt="Screenshot 2023-06-30 at 3 44 27 PM" src="https://github.com/bautistaaa/typehero/assets/31113245/c30929fe-68ca-407d-9894-ef2ea52ced3c">
+
+3. Click "Get connection strings".
+ <br/><img width="429" alt="Screenshot 2023-06-30 at 3 46 45 PM" src="https://github.com/bautistaaa/typehero/assets/31113245/c06a5829-92e6-417f-a5e6-083b7690923f">
+
+4. Switch to "Connect with Prisma" and copy the `DATABASE_URL` for `.env`
+ (replace **\*\*\*** with password)
+ <br/><img width="344" alt="Screenshot 2023-06-30 at 3 49 03 PM" src="https://github.com/bautistaaa/typehero/assets/31113245/4c9694ef-b954-47a8-9954-c2b677a1123a">
+
+### 3. Create a new GitHub OAuth Application
+
+[Follow this link][new-oauth] to create a new app filling the following required
+details on creation:
+
+```
+Homepage URL: http://localhost:3000
+Authorization callback URL: http://localhost:3000/api/auth/callback/github
+```
+
+Once completed, you will be redirected to the application page settings, from
+there create the client secret by clicking on `Generate a new client secret`
+button.
+
+Next, copy the client secret generated and the client ID into the `.env` file,
+replacing `<client_id>` and `<client_secret>`, respectively:
+
+```
+GITHUB_ID=<client_id>
+GITHUB_SECRET=<client_secret>
+```
+
+### 4. Setup uploadthing for file uploads
+
+Go to [uploadthing.com](https://uploadthing.com/dashboard) and create a project,
+then copy in the secrets into your `.env`.
+
+In the end your local `.env` file should look something like the following
+
+```
+DATABASE_URL="mysql://dev:dev@localhost/typehero"
+GITHUB_ID=very_real_github_id
+GITHUB_SECRET=very_real_secret
+
+UPLOADTHING_SECRET="very_real_uploadthing_secret"
+UPLOADTHING_APP_ID="very_real_uploadthing_app_id"
+# Next Auth
+# You can generate a new secret on the command line with:
+# openssl rand -base64 32
+# https://next-auth.js.org/configuration/options#secret
+NEXTAUTH_SECRET="for local use you can just use a garble of letters"
+NEXTAUTH_URL="http://localhost:3000"
+```
+
+### 5. Install dependencies
+
+Use `pnpm` to install dependencies.
+
+```
+pnpm install
+```
+
+### 6. Push Database Schema and Seed
+
+```
+pnpm db:push
+pnpm db:seed
+```
+
+### 7. Running the dev server
+
+Finally, you can run the dev server:
+
+```
+pnpm dev
+```
+
+### Sync data
+
+Once the server is running you can seed and sync data
+
+1. Navigate to
+ [http://localhost:3000/api/auth/github](http://localhost:3000/api/auth/github)
+ to authenticate with GitHub OAuth.
+
+[planetscale-quick-start]: https://planetscale.com/docs/tutorials/planetscale-quick-start-guide
+[new-oauth]: https://github.com/settings/applications/new
+
+#### Dependencies
+
+UI Library: [shadcn](https://ui.shadcn.com/)
+
+## FAQ
+
+<details>
+ <summary>How do I totally rebuild and re-seed the database?</summary>
+
+<p>Run the command</p>
+
+```
+pnpm refresh
+```
+
+This will cause prisma to force reset the database through the `db:reset`
+command and then run `db:seed`.
+
+</details>
+
+<details>
+ <summary>What if I run into errors with that command?</summary>
+ If you are using the docker setup for your local environment then get into the container with
+
+```sh
+docker exec -it typehero-db bash
+# we are in the container from here on
+$ mysql -u dev -p -h 127.0.0.1 typehero
+> drop database typehero;
+```
+
+Exit out of the container and then run
+
+```sh
+pnpm refresh
+```
+
+This tends to resolve the issue as it entirely destroys and rebuilds + reseeds the database.
+
+</details>
+<!-- Other stuff here? I can't think of anything -->
diff --git a/README.md b/README.md
index 7c2da25d..cabb86fa 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,31 @@
[![Type Hero Logo](/logo.svg)](https://typehero.dev/)
+[![Join the Trash Discord](https://discordapp.com/api/guilds/796594544980000808/widget.png?style=banner2)][trash-discord]
+
+<!-- do we want badge placeholders?? -->
+
# TypeHero
-Connect, collaborate, and grow with a community of TypeScript developers. Elevate your skills through interactive coding challenges, discussions, and knowledge sharing
+Connect, collaborate, and grow with a community of TypeScript developers.
+Elevate your skills through interactive coding challenges, discussions, and
+knowledge sharing
+
+## About Us
+
+TypeScript's typing system can be very powerful when used correctly. The problem
+is that most developers or engineers don't use much more than they have to in
+their day to day. Inevitably a moment comes where their knowledge just doesn't
+cut it for a use case, and they have to reach out to a community for help. We
+aim to be not only the community but the platform they can use to learn more of
+the intricacies of TypeScript's typing system.
## Quick Start
-Please see the [`CONTRIBUTING.md`](/CONTRIBUTING.md)
+Please see the [`LOCAL.md`](/LOCAL.md)
## Tech Stack
-Please see the [`package.json`](/package.json)
+We're largely a NextJS shop with TypeScript and MySQL. Checkout a full list at
+[`package.json`](/package.json)
+
+[trash-discord]: https://discord.gg/trashdev