docs: revise contributing, development, and readme (#4801)

Co-authored-by: Dimitri Mitropoulos <[email protected]>

CODE_OF_CONDUCT.md

@@ -1,8 +1,8 @@
 # Code of Conduct
 
-Like the technical community as a whole, the Insomnia community is made up of a mixture of professionals and volunteers from all over the world, working on every aspect of the mission – including mentorship, teaching, and connecting people.
+Like the technical community as a whole, the Insomnia community is made up of a mixture of professionals and volunteers from all over the world, working on every aspect of the mission - including mentorship, teaching, and connecting people.
 
-Diversity is a huge priority, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to. This code applies equally to founders, mentors and those seeking help and guidance. This isn’t an exhaustive list of things that you can’t do. Rather, take it in the spirit in which it’s intended - a guide to make it easier to enrich all of us and the technical communities in which we participate.
+Diversity is a huge priority, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to. This code applies equally to founders, mentors and those seeking help and guidance. This isn't an exhaustive list of things that you can't do. Rather, take it in the spirit in which it's intended - a guide to make it easier to enrich all of us and the technical communities in which we participate.
 
 This code of conduct applies to all spaces managed by the Insomnia project, including Slack, the issue tracker, and any other forums created for the project which the community uses for communication. In addition, violations of this code outside these spaces may affect a person's ability to participate within them.
 
@@ -11,7 +11,7 @@ If you believe someone is violating the code of conduct, we ask that you report
 - **Be friendly and patient.**
 - **Be welcoming.** We strive to be a community that welcomes and supports people of all   backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.
 - **Be considerate.** Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language.
-- **Be respectful.** Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the Insomnia community should be respectful when dealing with other members as well as with people outside the Insomnia community.
+- **Be respectful.** Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It's important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the Insomnia community should be respectful when dealing with other members as well as with people outside the Insomnia community.
 - **Be careful in the words that you choose.** We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior isn't acceptable. This includes, but is not limited to:
   - Violent threats or language directed against another person.
   - Discriminatory jokes and language.
@@ -21,7 +21,7 @@ If you believe someone is violating the code of conduct, we ask that you report
   - Unwelcome sexual attention.
   - Advocating for, or encouraging, any of the above behavior.
   - Repeated harassment of others. In general, if someone asks you to stop, then stop.
-- **When we disagree, try to understand why.** Disagreements, both social and technical, happen all the time and Insomnia is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. The strength of Insomnia comes from its varied community, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes.
+- **When we disagree, try to understand why.** Disagreements, both social and technical, happen all the time and Insomnia is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we're different. The strength of Insomnia comes from its varied community, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn't mean that they're wrong. Don't forget that it is human to err and blaming each other doesn't get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes.
 
 Original text courtesy of the [Speak Up! project](http://web.archive.org/web/20141109123859/http://speakup.io/coc.html).
 

CONTRIBUTING.md

@@ -34,6 +34,8 @@ Good pull requests (patches, improvements, new features) are a fantastic help. T
 
 **Please ask first** before embarking on any significant pull request (e.g. implementing features, refactoring code, porting to a different language), otherwise, you risk spending a lot of time working on something that might not get accepted into the project.
 
+If you plan on helping with development, please read the [Develop Insomnia](./README.md#develop-insomnia) section of the README for how to get started. The [Development Overview](./DEVELOPMENT.md) may also prove useful for a general overview of the application architecture.
+
 **IMPORTANT**: By submitting a patch, you agree to allow the project owner to license your work under the same license as that used by the project.
 
 ## Contributor T-shirt

DEVELOPMENT.md

@@ -4,20 +4,18 @@ The purpose of this document is to provide a general overview of the application
 
 ## Technologies
 
-Insomnia is a desktop application built on top of [Electron](http://electronjs.org/). Electron
-provides a Chromium runtime for the Insomnia web app to run inside of, as well as additional tools
-to provide access to operating system features.
+Insomnia is a desktop application built on top of [Electron](http://electronjs.org/). Electron provides a Chromium runtime for the Insomnia web app to run inside, as well as additional tools to provide access to operating system features.
 
 There are a few more technologies and tools worth mentioning:
 
 - [`React`](https://reactjs.org/) is the library used for all UI components.
 - [`styled-components`](https://styled-components.com/) and [`Less`](http://lesscss.org/) are used for styling UI components.
 - [`Electron Builder`](https://github.com/electron-userland/electron-builder) is used to help build, sign, and package Insomnia for distribution.
-- [`libcurl`](https://curl.se/libcurl/) is the library that Insomnia uses to make requests. Libcurl is the HTTP client of choice because it allows the deepest amount of debuggability and control of HTTP requests.
-- [`nedb`](https://github.com/louischatriot/nedb) a local in-memory database.
+- [`libcurl`](https://curl.se/libcurl/) is the library that Insomnia uses to make requests. We used libcurl as our HTTP client of choice because it allows the deepest amount of debuggability and control of HTTP requests.
+- [`NeDB`](https://github.com/louischatriot/nedb) a local in-memory database.
 - [`node-libcurl`](https://github.com/JCMais/node-libcurl) is a Node.js wrapper around the native libcurl library.
 - [`Codemirror`](https://codemirror.net/) is a web-based, extendable, code editor used for highlighting and linting of data formats like JSON, GraphQL, and XML.
-- [`Commander.js`](https://github.com/tj/commander.js) is used for building the inso CLI.
+- [`Commander.js`](https://github.com/tj/commander.js) is used for building the Inso CLI.
 
 ## Project Structure
 
@@ -30,32 +28,31 @@ Insomnia uses [`lerna`](https://lerna.js.org/) to manage multiple npm packages w
 
 `/packages/insomnia` is the entry point for the app. All other packages are imported from this one.
 
-There are a few notable directories inside of it:
+There are a few notable directories inside it:
 
 - `/main.development.js` Entry for Electron.
 - `/src/main` Stuff that runs inside Electron's main process.
 - `/src/ui` React components and styling.
 - `/src/common` Utilities used across both main and render processes.
 - `/src/plugins` Logic around installation and usage of plugins.
 - `/src/models` DB models used to store user data.
-- `/src/network` Sending requests and performing auth (eg. OAuth 2).
+- `/src/network` Sending requests and performing auth (e.g. OAuth 2).
 - `/src/templating` Nunjucks and rendering related code.
-- `/src/sync(-legacy)?` and `/src/accounts` Team sync and account stuff.
+- `/src/sync` and `/src/account` Team sync and account stuff.
 
 ## Data and State Architecture
 
 Insomnia stores data in a few places:
 
-- A local in-memory NeDB database stores data for data models (requests, folder, workspaces, etc).
+- A local in-memory NeDB database stores data for data models (requests, folder, workspaces, etc.).
 - A local Redux store contains an in-memory copy of all database entities.
 - Multiple React Context stores, defined in `/src/ui/context`.
 
-> Note: Eventually, Redux could/should be removed, which would both reduce memory overhead and simplify the codebase. NeDB should essentially replace it
+> Note: NeDB is officially unmaintained (even for criticl security bugs) and was last published in February 2016. Due to this, we hope to move away from it, however doing so is tricky because of how deeply tied it is to our architecture.
 
 ## Automated testing
 
-We use [Jest](https://jestjs.io/) and [react-testing-library](https://testing-library.com/docs/react-testing-library)
-to write our unit tests, and [Playwright](https://github.com/microsoft/playwright) for integration tests.
+We use [Jest](https://jestjs.io/) and [react-testing-library](https://testing-library.com/docs/react-testing-library) to write our unit tests, and [Playwright](https://github.com/microsoft/playwright) for integration tests.
 
 Unit tests exist alongside the file under test. For example:
 
@@ -70,8 +67,8 @@ The structure for smoke tests is explained in the smoke testing package: [`packa
 
 This is just a brief summary of Insomnia's current technical debt.
 
-- Loading large responses (~20MB) can crash the app on weaker hardware.
-- An in-memory duplicate of the local DB is stored in Redux, unnecessarily doubling memory usage. Moving forward, Redux shouldn't need to be considered much and may be able to be removed eventually.
+- Loading large responses (~20 MB) can crash the app on weaker hardware.
+- An in-memory duplicate of the local DB is stored in Redux.
 - Bundling `libcurl` (native module) has caused many weeks of headaches trying to get builds working across Windows, Mac, and Linux. More expertise here is definitely needed.
-- All input fields that support templating/autocomplete/etc are actually Codemirror instances. This isn't really debt but may affect things going forward.
+- All input fields that support features like templating or code completion are actually [CodeMirror](https://codemirror.net/6/) instances. This isn't really debt, but may affect things going forward.
 - Use of `libcurl` means Insomnia can't run in a web browser and can't support bidirectional socket communication.

README.md

@@ -16,12 +16,9 @@ from the website.
 
 ## Bugs and Feature Requests
 
-Have a bug or a feature request? First, read the
-[issue guidelines](CONTRIBUTING.md#using-the-issue-tracker) and search for existing and
-closed issues. If your problem or idea is not addressed yet, [please open a new issue](/issues).
+Have a bug or a feature request? First, read the [issue guidelines](CONTRIBUTING.md#using-the-issue-tracker) and search for existing and closed issues. If your problem or idea is not addressed yet, [please open a new issue](/issues).
 
-For more generic product questions and feedback, join the [Slack Team](https://chat.insomnia.rest) or email
-[[email protected]](mailto:[email protected])
+For more generic product questions and feedback, join the [Slack Team](https://chat.insomnia.rest) or email [[email protected]](mailto:[email protected])
 
 ## Contributing
 
@@ -38,7 +35,7 @@ Development on Insomnia can be done on Mac, Windows, or Linux as long as you hav
 <details>
 <summary>Initial Dev Setup</summary>
 
-This repository is structured as a monorepo and contains many Node.JS packages. Each package has its own set of commands, but the most common commands are available from the root [`package.json`](package.json) and can be accessed using the `npm run ...` command. Here are the only three commands you should need to start developing on the app.
+This repository is structured as a monorepo and contains many Node.JS packages. Each package has its own set of commands, but the most common commands are available from the root [`package.json`](package.json) and can be accessed using the `npm run …` command. Here are the only three commands you should need to start developing on the app.
 
 ```shell
 # Install and Link Dependencies
@@ -96,8 +93,8 @@ If you are on Windows and have problems, you may need to install [Windows Build
 
 You can use any editor you'd like, but make sure to have support/plugins for the following tools:
 
-- [ESLint](http://eslint.org/) – For catching syntax problems and common errors
-- [JSX Syntax](https://facebook.github.io/react/docs/jsx-in-depth.html) – For React components
+- [ESLint](http://eslint.org/) - For catching syntax problems and common errors
+- [JSX Syntax](https://facebook.github.io/react/docs/jsx-in-depth.html) - For React components
 
 </details>
 
@@ -113,9 +110,9 @@ Search for, discover, and install plugins from the Insomnia [Plugin Hub](https:/
 
 ## Community Projects
 
-- [Insomnia Documenter](https://github.com/jozsefsallai/insomnia-documenter) – Generate beautiful API documentation pages using the [documenter plugin](https://insomnia.rest/plugins/insomnia-plugin-documenter) or your Insomnia export file.
-- [GitHub API Spec Importer](https://github.com/swinton/github-rest-apis-for-insomnia) – A complete set of GitHub REST API route specifications that can be imported straight into Insomnia.
-- [Swaggymnia](https://github.com/mlabouardy/swaggymnia) – Generate [Swagger](https://swagger.io/) documentation for your existing API in Insomnia.
+- [Insomnia Documenter](https://github.com/jozsefsallai/insomnia-documenter) - Generate beautiful API documentation pages using the [documenter plugin](https://insomnia.rest/plugins/insomnia-plugin-documenter) or your Insomnia export file.
+- [GitHub API Spec Importer](https://github.com/swinton/github-rest-apis-for-insomnia) - A complete set of GitHub REST API route specifications that can be imported straight into Insomnia.
+- [Swaggymnia](https://github.com/mlabouardy/swaggymnia) - Generate [Swagger](https://swagger.io/) documentation for your existing API in Insomnia.
 
 ## License