Merge pull request #2358 from hey-api/docs/contributing-overview

docs: add contributor manual overview

Author: mrlubos

docs/.vitepress/config/en.ts

@@ -5,6 +5,10 @@ export default defineConfig({
     '🚀 The OpenAPI to TypeScript codegen. Generate clients, SDKs, validators, and more.',
   lang: 'en-US',
   themeConfig: {
+    editLink: {
+      pattern: 'https://github.com/hey-api/openapi-ts/edit/main/docs/:path',
+      text: 'Edit',
+    },
     footer: {
       message: 'Released under the MIT License.',
     },
@@ -14,6 +18,10 @@ export default defineConfig({
         text: 'Sponsor Hey API',
       },
     ],
+    outline: {
+      label: 'Table of Contents',
+      level: 2,
+    },
     sidebar: [
       {
         items: [
@@ -236,6 +244,21 @@ export default defineConfig({
             text: 'Spotlight',
           },
           {
+            collapsed: true,
+            items: [
+              {
+                link: '/openapi-ts/community/contributing/building',
+                text: 'Building',
+              },
+              {
+                link: '/openapi-ts/community/contributing/developing',
+                text: 'Developing',
+              },
+              {
+                link: '/openapi-ts/community/contributing/testing',
+                text: 'Testing',
+              },
+            ],
             link: '/openapi-ts/community/contributing',
             text: 'Contributing',
           },

docs/.vitepress/config/shared.ts

@@ -64,7 +64,8 @@ export default defineConfig({
       provider: 'local',
     },
     socialLinks: [
-      { icon: 'npm', link: 'https://npmjs.com/package/@hey-api/openapi-ts' },
+      { icon: 'linkedin', link: 'https://linkedin.com/company/heyapi' },
+      { icon: 'x', link: 'https://x.com/mrlubos' },
       { icon: 'github', link: 'https://github.com/hey-api/openapi-ts' },
     ],
   },

docs/.vitepress/theme/components/FeatureStatus.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+const props = defineProps<{
+  issueNumber: number;
+  name: string;
+}>();
+</script>
+
+<template>
+  <div class="warning custom-block">
+    <p class="custom-block-title">Excited about {{ props.name }}?</p>
+    <p>
+      Help us prioritize this feature by voting on
+      <a
+        :href="`https://github.com/hey-api/openapi-ts/issues/${props.issueNumber}`"
+        rel="noreferrer"
+        target="_blank"
+        >GitHub</a
+      >
+      or consider becoming a
+      <a href="/openapi-ts/community/spotlight">contributor</a>.
+    </p>
+  </div>
+</template>

docs/.vitepress/theme/components/Heading.vue

@@ -1,5 +1,11 @@
+<script setup lang="ts">
+const props = defineProps<{
+  spaceBetween?: boolean;
+}>();
+</script>
+
 <template>
-  <div class="container">
+  <div class="container" :class="{ 'space-between': props.spaceBetween }">
     <slot />
   </div>
 </template>
@@ -10,4 +16,8 @@
   column-gap: 1rem;
   display: flex;
 }
+
+.space-between {
+  justify-content: space-between;
+}
 </style>

docs/.vitepress/theme/index.ts

@@ -6,6 +6,7 @@ import DefaultTheme from 'vitepress/theme';
 import './custom.css';
 
 import AuthorsList from './components/AuthorsList.vue';
+import FeatureStatus from './components/FeatureStatus.vue';
 import Heading from './components/Heading.vue';
 import VersionLabel from './components/VersionLabel.vue';
 import VersionSwitcher from './components/VersionSwitcher.vue';
@@ -15,6 +16,7 @@ export default {
   Layout,
   enhanceApp: ({ app }) => {
     app.component('AuthorsList', AuthorsList);
+    app.component('FeatureStatus', FeatureStatus);
     app.component('Heading', Heading);
     app.component('VersionLabel', VersionLabel);
     app.component('VersionSwitcher', VersionSwitcher);

docs/openapi-ts/clients/axios.md

@@ -12,10 +12,6 @@ import { embedProject } from '../../embed'
   <VersionLabel value="v1" />
 </Heading>
 
-::: warning
-Axios client is currently in beta. The interface might change before it becomes stable. We encourage you to leave feedback on [GitHub](https://github.com/hey-api/openapi-ts/issues).
-:::
-
 ### About
 
 [Axios](https://axios-http.com) is a simple promise based HTTP client for the browser and Node.js. Axios provides a simple to use library in a small package with a very extensible interface.

docs/openapi-ts/clients/fetch.md

@@ -9,10 +9,6 @@ import { embedProject } from '../../embed'
 
 # Fetch API
 
-::: warning
-Fetch API client is currently in beta. The interface might change before it becomes stable. We encourage you to leave feedback on [GitHub](https://github.com/hey-api/openapi-ts/issues).
-:::
-
 ### About
 
 The [Fetch API](https://developer.mozilla.org/docs/Web/API/Fetch_API) provides an interface for fetching resources (including across the network). It is a more powerful and flexible replacement for XMLHttpRequest.

docs/openapi-ts/clients/next-js.md

@@ -5,10 +5,6 @@ description: Next.js client for Hey API. Compatible with all our features.
 
 # Next.js
 
-::: warning
-Next.js client is currently in beta. The interface might change before it becomes stable. We encourage you to leave feedback on [GitHub](https://github.com/hey-api/openapi-ts/issues).
-:::
-
 ### About
 
 [Next.js](https://nextjs.org) is the React framework for the web. Used by some of the world's largest companies, Next.js enables you to create high-quality web applications with the power of React components.

docs/openapi-ts/community/contributing.md

@@ -1,21 +1,42 @@
 ---
 title: Contributing
-description: Learn how to contribute to @hey-api/openapi-ts.
+description: Learn how to contribute to Hey API.
 ---
 
-# Contributing
+# Contributor Manual
 
-Thank you for considering contributing to Hey API. In order to increase the likelihood of your changes being merged, first open an issue if one does not already exist. Once an issue exists, let us know you'd like to work on it. We will confirm whether we're looking to resolve the issue and provide you with guidance if required. This is to ensure our codebase remains in good state and all features contribute to Hey API's objectives.
+## Foreword
 
-## Prerequisites
+Hey API is building an OpenAPI to TypeScript code generator ecosystem. It’s trusted by thousands of companies – from YC startups to Fortune 500 enterprises – and powers products used by millions worldwide.
 
-You should have a working knowledge of [git](https://git-scm.com), [node](https://nodejs.org/en), and [pnpm](https://pnpm.io).
+We welcome contributors of all backgrounds and experience levels. Whether you’re fixing a typo or building a new feature, your input matters. If you need guidance, help with technical writing, or want to bring a feature idea to life, we’re here to support you.
 
-## Guidelines
+::: tip
 
-Your [pull request](https://help.github.com/articles/using-pull-requests) must:
+New to open source? Take a look at the [Open Source](https://opensource.guide/) or [First Contributions](https://github.com/firstcontributions/first-contributions) guides for helpful information on contributing to open source projects.
 
-- address a single issue or add a single item of functionality
-- contain a clean history of small, incremental, logically separate commits, with no merge commits
-- use clear commit messages
-- be possible to merge automatically
+:::
+
+## First Steps
+
+There are many ways to contribute to Hey API. Most of them don't involve writing any code!
+
+- **Read the documentation**. Start with the [Get Started](/openapi-ts/get-started) guide. If you find anything broken or confusing, you can suggest improvements by clicking "Edit" at the bottom of any page.
+
+- **Browse open issues**. Help others by providing workarounds, asking for clarification, triaging, or suggesting labels on [open issues](https://github.com/hey-api/openapi-ts/issues). If you see something you would like to work on, consider opening a pull request.
+
+- **Participate in discussions**. Ask or [answer questions](https://github.com/orgs/hey-api/discussions), provide feedback, or suggest new ideas. Every idea is welcome, no matter how big or small.
+
+- **Engage on social media**. Help others discover Hey API by engaging with our posts on [LinkedIn](https://linkedin.com/company/heyapi), [Bluesky](https://bsky.app/profile/heyapi.dev), or [X](https://x.com/mrlubos). Share your experiences with Hey API on Reddit, Slack, or in your own communities and group chats.
+
+- **Create a new issue**. If you can't find a solution, [open an issue](https://github.com/hey-api/openapi-ts/issues). The issue template will guide you through the process.
+
+- **Open a pull request**. If you find an issue you would like to fix, open a pull request. If you need help, tag [`@mrlubos`](https://github.com/mrlubos) on GitHub, provide enough relevant information, and we will do our best to assist you.
+
+These are some of the best ways not only to contribute to Hey API, but also to learn, connect with others, and share ideas.
+
+## Pull Requests
+
+Ready to write some code? We have dedicated guides to help you [build](/openapi-ts/community/contributing/building), [develop](/openapi-ts/community/contributing/developing), and [test](/openapi-ts/community/contributing/testing) your feature before it's released.
+
+We are excited to see what you’ll contribute!

docs/openapi-ts/community/contributing/building.md

@@ -0,0 +1,23 @@
+---
+title: Building
+description: Learn how to contribute to Hey API.
+---
+
+# Building
+
+::: warning
+This page is under construction. We appreciate your patience.
+:::
+
+## Prerequisites
+
+You should have a working knowledge of [git](https://git-scm.com), [node](https://nodejs.org/en), and [pnpm](https://pnpm.io).
+
+## Guidelines
+
+Your [pull request](https://help.github.com/articles/using-pull-requests) must:
+
+- address a single issue or add a single item of functionality
+- contain a clean history of small, incremental, logically separate commits, with no merge commits
+- use clear commit messages
+- be possible to merge automatically