docs: improve contributing docs

CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing
+
+Thanks for being willing to contribute!
+
+**Working on your first Pull Request?** You can learn how from this _free_
+series [How to Contribute to an Open Source Project on GitHub][egghead]
+
+## Project setup
+
+1.  Fork and clone the repo
+2.  Run `npm ci` to install dependencies
+3.  Create a branch for your PR with `git checkout -b feature/your-branch-name`
+
+> Tip: Keep your `main` branch pointing at the original repository and make
+> pull requests from branches on your fork. To do this, run:
+>
+> ```
+> git remote add upstream git@github.com:smeijer/next-runtime.git
+> git fetch upstream
+> git branch --set-upstream-to=upstream/main main
+> ```
+>
+> This will add the original repository as a "remote" called "upstream," Then
+> fetch the git information from that remote, then set your local `main`
+> branch to use the upstream main branch whenever you run `git pull`. Then you
+> can make all of your pull request branches based on this `main` branch.
+> Whenever you want to update your version of `main`, do a regular `git pull`.
+
+## Committing and Pushing changes
+
+Please make sure to run the tests before you commit your changes. You can run
+`npm run test` to do so.
+
+### Linting with git hooks
+
+There are git hooks set up with this project that are automatically installed
+when you install dependencies. They're really handy, and will take care of linting
+and formatting for you.
+
+## Project structure
+
+There are a few surprising things going on in this repo. We have two test runners, as well as two tsconfig files. Let me explain why;
+
+**npm run test:unit**
+
+This is a basic ts-jest runner that runs tests located in `./src`. The tests will use a fake next server to test our functionality, without depending on a next build.
+
+**npm run test:e2e**
+
+These are tests run by playwright, against a real next instance. Running next means that we need a `/pages` directory. Hence, the test files are located in `/pages`. That directory now serves as place for e2e tests, which can also serve as "examples".
+
+**tsconfig.build.json**
+
+`test:e2e` is also the reason why we need two tsconfigs. `tsconfig.build.json` is used to build the lib. Because the spawning of next for e2e tests, automatically create or adjusts the main `tsconfig.json`. Which breaks our build.
+
+**/src**
+
+That's where you find all the source files for `next-runtime`.
+
+**/docs**
+
+Is where you'll find the documentation. Run `npm run dev` in that directory to start the documentation webserver. All documentation content files can be found in `/docs/content`.
+
+## Help needed
+
+Please check out the [the open issues][issues]
+
+Also, please watch the repo and respond to questions/bug reports/feature
+requests! Thanks!
+
+[egghead]: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github
+[issues]: https://github.com/smeijer/next-runtime/issues

MAINTAINING.md

@@ -0,0 +1,65 @@
+# Maintaining
+
+This is documentation for maintainers of this project.
+
+## Code of Conduct
+
+Please review, understand, and be an example of it. Violations of the code of
+conduct are taken seriously, even (especially) for maintainers.
+
+## Issues
+
+We want to support and build the community. We do that best by helping people
+learn to solve their own problems. We have an issue template and hopefully most
+folks follow it. If it's not clear what the issue is, invite them to create a
+minimal reproduction of what they're trying to accomplish or the bug they think
+they've found.
+
+Once it's determined that a code change is necessary, point people to
+[makeapullrequest.com][make-a-pr] and invite them to make a
+pull request. If they're the one who needs the feature, they're the one who can
+build it. If they need some hand holding and you have time to lend a hand,
+please do so. It's an investment into another human being, and an investment
+into a potential maintainer.
+
+Remember that this is open source, so the code is not yours, it's ours. If
+someone needs a change in the codebase, you don't have to make it happen
+yourself. Commit as much time to the project as you want/need to. Nobody can ask
+any more of you than that.
+
+## Pull Requests
+
+As a maintainer, you're fine to make your branches on the main repo or on your
+own fork. Either way is fine.
+
+When we receive a pull request, a various automated checks are kicked off
+automatically. We avoid merging anything that doesn't pass these checks.
+
+Please review PRs and focus on the code rather than the individual. You never
+know when this is someone's first ever PR and we want their experience to be as
+positive as possible, so be uplifting and constructive.
+
+When you merge the pull request, 99% of the time you should use the
+[Squash and merge][squash-and-merge]
+feature. This keeps our git history clean, but more importantly, this allows us
+to make any necessary changes to the commit message so we release what we want
+to release. See the next section on Releases for more about that.
+
+## Release
+
+Documentation changes are released automatically. They happen whenever changes land into `main`. A netlify build gets kicked off, and the [documentation site][docs] gets updated.
+
+Library versions are published manually. Run `npm run release {pach|minor|major}` in the root of this project, and a new git tag will be pushed, a changelog is written to github releases, and a new version will be published to npm.
+
+The changelog is generated based on the git commit messages. With this
+in mind, **please brush up on [the commit message convention][commit] which
+drives our releases.**
+
+## Thanks!
+
+Thank you so much for helping to maintain this project!
+
+[commit]: https://github.com/conventional-changelog-archived-repos/conventional-changelog-angular/blob/ed32559941719a130bb0327f886d6a32a8cbc2ba/convention.md
+[squash-and-merge]: https://help.github.com/articles/merging-a-pull-request/
+[make-a-pr]: http://makeapullrequest.com
+[docs]: https://next-runtime.meijer.ws/

README.md

@@ -57,34 +57,15 @@ export default function Home({ name, message }) {
 }
 ```
 
-## Contributing
-
-There are a few surprising things going on in this repo. We have two test runners, as well as two tsconfig files. Let me explain why;
-
-**npm run test:unit**
-
-This is a basic ts-jest runner that runs tests located in `./src`. The tests will use a fake next server to test our functionality, without depending on a next build.
-
-**npm run test:e2e**
-
-These are tests run by playwright, against a real next instance. Running next means that we need a `/pages` directory. Hence, the test files are located in `/pages`. That directory now serves as place for e2e tests, which can also serve as "examples".
-
-**tsconfig.build.json**
-
-`test:e2e` is also the reason why we need two tsconfigs. `tsconfig.build.json` is used to build the lib. Because the spawning of next for e2e tests, automatically create or adjusts the main `tsconfig.json`. Which breaks our build.
-
-**/src**
-
-That's where you find all the source files for `next-runtime`.
-
-**/docs**
-
-Is where you'll find the documentation. Run `npm run dev` in that directory to start the documentation webserver. All documentation content files can be found in `/docs/content`.
-
 ## Sponsor
 
 Are you, or your employer, a satisfied user of this, or any of [my other projects](https://meijer.ws/open-source). Then please [consider sponsoring](https://github.com/sponsors/smeijer) my work so I can dedicate more time to maintaining this kind of projects.
 
+## Contributing
+
+Please check [contributing.md](/CONTRIBUTING.md). It contains info about the structure of this repo
+to help you get up and running.
+
 ## Contributors
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):