Merge pull request #39 from joshwcomeau/final-docs-and-stuff

Tweak documentation ahead of release. Create v0.0.1

CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing
+
+Thanks for your interest in Guppy! We are open to, and grateful for, any contributions made by the community. We want Guppy to be a community endeavour, all of us working together to make web development more accessible for folks who don't have terminal experience!
+
+## Reporting Issues and Asking Questions
+
+Before opening an issue, please search the [issue tracker](https://github.com/joshwcomeau/guppy/issues) to make sure your issue hasn't already been reported.
+
+### Bugs and Improvements
+
+_Guppy is alpha software_, and you will likely encounter some issues.
+
+We use the issue tracker to keep track of bugs and improvements to Guppy itself, its examples, and the documentation. We encourage you to open issues to discuss improvements, architecture, theory, internal implementation, etc. If a topic has been discussed before, we will ask you to join the previous discussion.
+
+## Development
+
+Visit the [issue tracker](https://github.com/joshwcomeau/guppy/issues) to find a list of open issues that need attention. The best way to contribute is to find something you feel able and willing to tackle. As the project matures we hope to add more "good first contribution" issues for folks newer to React development.
+
+Fork, then clone the repo:
+
+```
+git clone https://github.com/your-username/redux.git
+```
+
+### Running
+
+#### Local development
+
+You can get started developing locally by running the `start` task:
+
+```
+npm run start
+```
+
+This should open an Electron window with the application running.
+
+In development, all projects are created at `~/guppy-projects-dev`
+
+You can build a MacOS executable by running:
+
+```
+npm run package
+```
+
+The result will be in the `release-builds` folder.
+
+### Testing and Linting
+
+Unfortunately, very little of Guppy is currently tested.
+
+We hope to add more tests in the meantime, as well as add CI integration to run tests on push, but for now you can run the tests with:
+
+```
+npm run test
+```
+
+This project uses Prettier, this should be run automatically on commit.
+
+### Docs
+
+Please learn more about Guppy at the project [README](https://github.com/joshwcomeau/guppy/blob/master/README.md), or the docs located in the [/docs](https://github.com/joshwcomeau/guppy/tree/master/docs) directory.
+
+### Sending a Pull Request
+
+For non-trivial changes, please open an issue with a proposal for a new feature or refactoring before starting on the work, or comment on an existing requested-feature issue. We don't want you to waste your efforts on a pull request that we won't want to accept.
+
+On the other hand, sometimes the best way to start a conversation _is_ to send a pull request. Use your best judgement!
+
+In general, the contribution workflow looks like this:
+
+- Find or open a new issue in the [Issue tracker](https://github.com/joshwcomeau/guppy/issues).
+- Fork the repo.
+- Create a new feature branch based off the `master` branch.
+- Make sure all tests pass
+- Submit a pull request, referencing any issues it addresses.
+
+Please try to keep your pull request focused in scope and avoid including unrelated commits.
+
+After you have submitted your pull request, we'll try to get back to you as soon as possible. We may suggest some changes or improvements.
+
+Thank you for contributing!

README.md

@@ -2,24 +2,36 @@
 
 ### A friendly application manager and task runner for React.js
 
-> This is a temporary README and should be rewritten pre-launch
+![Guppy project screen](https://github.com/joshwcomeau/guppy/raw/master/docs/images/main-image.png)
 
 There are a lot of "meta" skills around React web development that don't really have anything to do with building great web products.
 
 For example, the terminal. For those of us who didn't grow up on a unix shell, the terminal is an inscrutable box of cryptic and indecipherable commands. It's undoubtedly powerful, and a valuable skill to develop... but should it really be a pre-requisite for modern web development?
 
-Guppy is a desktop application designed to make it easier to get started building React web products. It provides a friendly GUI for many of the typical tasks facing React developers:
+Guppy is a free-to-use desktop application designed to make it easier to get started building React web products. It provides a friendly GUI for many of the typical tasks facing React developers:
 
 - Creating new projects
 - Running a development server
 - Executing tasks (building for production, running tests, ...)
 - Managing dependencies (adding, updating, searching)
 
-Guppy is made for beginners - folks who are just starting out with web development. We hope that it's powerful enough for advanced users as well, but we'll always prioritize the new-developer experience.
+Guppy is made for beginners - folks who are just starting out with web development. We hope that it's powerful enough for advanced users as well, but we'll always prioritize the new-developer experience. We'll never charge money for Guppy, it'll always be free-to-use.
+
+> **NOTE**: This is _super early pre-release alpha_. Truthfully it's probably not ready for beginner usage yet (there may be frustrating bugs, plus it only runs on MacOS). The goal is to build a community of folks to work on this and create something truly useful and wonderful for beginners.
+
+### Download
+
+[Download Guppy]() (TODO: Add link)
+
+For more information on setup, see [Installation](#installation) below.
 
 ### Current Status
 
-This project is in early pre-release Alpha. We hope to collect feedback and eventually wind up with a rock-solid tool, but for now there may be tons of bugs and missing functionality.
+This project is in early pre-release Alpha.
+
+Want to help build something great for newcomers? We're actively looking for contributors to help develop this pre-release alpha into something amazing. This is a great time to get involved and help shape the future of Guppy!
+
+Also, important to note: this is a side-project worked on during spare time. We appreciate any bug reports, but realistically we may not be able to fix issues in a timely manner (feel free to contribute fixes though!)
 
 ### Platform Support
 
@@ -31,16 +43,26 @@ Want to help build Guppy? This is the biggest missing feature right now, and con
 
 To use Guppy, you'll first need to have a modern version of Node (a Javascript runtime) installed. [Download Node](https://nodejs.org/en/download/current/).
 
-Once Node is installed, you can [download Guppy]().
+Once Node is installed, you can [download Guppy]() (TODO: Add link).
 
-That's it! Double-click Guppy to open it.
+Double-click the downloaded executable to open Guppy.
 
 > Note: In future stable releases, I hope to remove the need to download Node by using the Node runtime that comes with Guppy. I also plan to create a proper installer so that it's easy to copy Guppy to the Applications folder. Contributions welcome!
 
 ### Getting Started
 
 Learn more about using Guppy in our [Getting Started guide](https://github.com/joshwcomeau/guppy/blob/master/docs/getting-started.md).
 
+### How it works
+
+Guppy is an electron application that secretly runs terminal commands for you in the background. It uses **create-react-app** and **gatsby-cli**. Support could conceivably be added for Next, and other project types (including non-React ones)
+
+Guppy adds a new top-level key to your `package.json` to store project-related information. It also reads from `package.json` to figure out the current dependencies, and see which tasks are available (via `scripts`).
+
+Guppy has intelligent modules built around task types. For example, the dev server is no ordinary task, it's one that ought to be running throughout your time working on the project, and so it's given its own module at the top of the page.
+
+For more information on learning more about Guppy and contributing, see our [contribution docs](https://github.com/joshwcomeau/guppy/blob/master/CONTRIBUTING.md)
+
 ### Future Vision
 
 Right now, Guppy's feature-set is pretty limited. It consists of 3 modules: a "dev-server" pane, a "tasks" pane, and a "dependencies" pane.
@@ -52,23 +74,3 @@ The first big change I'd like to see is better support for common dev tools like
 - Dependencies should be easy to update. I imagine an "update core dependencies" button that updates react, react-dom, and any associated packages, with built-in codemod support. I imagine it being able to find security problems (via [`npm audit`](https://docs.npmjs.com/getting-started/running-a-security-audit)).
 
 I'd also like to see Guppy become far more useful for educating users about web development. The philosophy of Guppy is that anybody can learn web development, and it should provide resources to help learners along. Guppy has full access to the project code and settings, and so I wonder if there are opportunities to suggest solutions to problems the user runs into... I don't have any concrete ideas yet, but it's interesting to think about.
-
-### How it works
-
-Guppy is an electron application that secretly runs terminal commands for you in the background. It uses **create-react-app**, with support coming soon for other project types, like Gatsby and Next.
-
-Guppy adds a new key to your `package.json` to store project-related information. It also reads from `package.json` to figure out the current dependencies, and see which tasks are available (via `scripts`).
-
-Originally, Guppy was going to be much more agnostic about project type. I had imagined that it would treat every `script` as a task, and they'd all work exactly the same way. I realized that this isn't very helpful, though; the tasks you want to perform are radically different, and should be treated as such!
-
-For example, the common script for running a development server is `start`. This is a long-running task, though, and extremely important for local development. Guppy separates it in the UI to have its own module. I can also imagine doing this for all of the built-in scripts, so that only user-defined scripts are treated generically.
-
-### Code Organization
-
-This project uses React and Redux. I'm also experimenting with holding most logic in "services". These are just modules (in `src/services`) that manage specific things, like creating a project, finding an available port, or helping provide routing info. They're essentially helper modules, but all geared around specifc tasks.
-
-A lot of the task-running logic lives in `middlewares/task.middleware.js`. This may move into a service at some point.
-
-### Temporary development notes
-
-This project is a create-react-app project, using Electron. I followed the instructions at https://medium.freecodecamp.org/building-an-electron-application-with-create-react-app-97945861647c (well, mostly; instead of using Foreman, I used concurrently, and came up with my own scripts strategy. But overall I mostly followed that blog post).

TODO.md

@@ -0,0 +1,4 @@
+- Fix tests
+- Add prettier script
+- on-commit hook
+- Check that all the docs make sense

docs/adding-a-project.md

@@ -1,4 +1,4 @@
-# Getting Started with Guppy
+# Adding a Project
 
 > Guppy is a companion tool that aims to totally replace the terminal, so that newcomers to the field aren't burdened with a whole other skillset they need to learn before they can get started building cool things.
 >
@@ -8,14 +8,19 @@
 
 ## Installation
 
-Read the [Installation Guide](todo) to get the application downloaded and running.
+Installation instructions in the [README](https://github.com/joshwcomeau/guppy/blob/master/README.md#installation).
 
 ## Your First Project
 
 Guppy works on a per-project basis: each project has its own area in Guppy's interface. So, the first thing we need is a project to work on!
 
 The intro screen presents two options: "Create a new web application" and "import an existing project".
 
+You can also access these options at any time through the application menu:
+
+- `File -> Create New Project` (keyboard shortcut: `⌘N`)
+- `File -> Import Existing Project` (keyboard shortcut: `⌘I`)
+
 ### Creating a New Project
 
 Choose this option if you want to start a brand new project.
@@ -24,17 +29,17 @@ The wizard will guide you through the process, but this guide will add some addi
 
 #### Project Name
 
-Your project name can be whatever you want! Special characters are cool. So are emoji 🎉 give it whatever name you want.
+Your project name can be whatever you'd like! Special characters are cool. So are emoji 🎉.
 
-There is currently no way to change the project name from within Guppy, but you can always [modify the package.json](todo) to use a different name.
+> There is currently no way to change the project name from within Guppy, but you can always modify the project's package.json to use a different name.
 
 #### Project Type
 
 There are currently 2 types of supported projects: Vanilla React, and Gatsby.
 
-**Vanilla React** is a minimal yet fully-ready-to-go solution for getting started with React development. It uses [create-react-app]() behind the scenes, a tool built by Facebook, and has become the standard way that new applications are created, for beginners and experienced developers alike.
+**Vanilla React** is a minimal yet fully-ready-to-go solution for getting started with React development. It uses [create-react-app](https://github.com/facebook/create-react-app) behind the scenes, a tool built by Facebook, and has become the standard way that new applications are created, for beginners and experienced developers alike.
 
-**Gatsby** is an amazing project that strives to be a static site generator, somewhat like Jekyll. It does a bunch of powerful performance optimizations, so the site you build is lightning-quick. It also has a vibrant community behind it! If you're building a static site (eg. a blog, something informational), it can be a huge productivity boost.
+[**Gatsby**](https://www.gatsbyjs.org/) is a supercharged static site generator that does a bunch of optimizations to be lightning quick. It also has a vibrant community behind it! If you're building a static site (eg. a blog, something informational), it can be a huge productivity boost.
 
 > NOTE: Gatsby has a wide array of "starters" for different usecases, but Guppy doesn't support them yet. We'll add this in a future update, but for now it might be best to create the product through a terminal and then import it into Guppy. See [their official docs](https://www.gatsbyjs.org/tutorial/part-one/#check-your-development-environment) for more information.
 
@@ -46,4 +51,18 @@ Ultimately, the project type you choose depends on your goals. Some thoughts:
 
 - Are you looking to build a blog, landing page, or other content-based product? "Gatsby" can save you a ton of time, and is likely the best choice.
 
-####
+#### Project Icon
+
+When you have multiple projects, it's helpful to have a quick, visual way to tell them apart. Your project's icon is useful for jumping around quickly in Guppy.
+
+Note that this icon is not intended to be used within your application, it's simply for Guppy administration.
+
+> In the future, we'll add the ability to use the project's favicon, or upload your own photo. For now, though, we're afraid the only choices are a handful of royalty-free shots.
+
+### Importing an Existing Project
+
+If you've built a create-react-app or Gatsby project outside of Gatsby, you may be able to import it to use within Guppy.
+
+Guppy will save a reference to that project, so that the next time you open Guppy, that project is remembered. If the project's path on the disk changes, like if you move it to another directory, you'll need to re-import it, but all of the settings will be saved (we store this information in your project's package.json, so Guppy will always recognize it when it's re-imported, even if it's on another computer!).
+
+To import a project, use the option in the menu at `File -> Import Existing Project` (keyboard shortcut: `⌘I`).

docs/getting-started.md

@@ -2,21 +2,23 @@
 
 > Guppy is a companion tool that aims to totally replace the terminal, so that newcomers to the field aren't burdened with a whole other skillset they need to learn before they can get started building cool things.
 >
-> It's currently in Alpha, which means that we're still a long way from fully realizing that dream. You may run into bugs, and it's only compatible with certain types of projects, and certain operating systems.
+> It's currently in pre-release Alpha, which means that we're still a long way from fully realizing that dream. You may run into bugs, and it may not be compatible with your existing projects or operating system.
 >
-> Apologies in advance for any trouble you run into. Please leave feedback!
+> Apologies in advance for any trouble you run into! Contributions welcome.
 
 ## Installation
 
-Installation instructions in the main README. [ADD LINK]
+Installation instructions in the [README](https://github.com/joshwcomeau/guppy/blob/master/README.md#installation).
 
 ## Adding your first project
 
 To create your first project, click "Create a new web application" at the bottom of the main screen.
 
 The wizard will guide you through selecting a name, icon, and project type.
 
-If you already have a project that you'd like to use with Guppy, you can opt to import an existing project instead. _Please be advised that this feature hasn't been rigorously tested!_ It will only work with projects created with Gatsby or create-react-app, and may in the worst case totally mess up your project's `package.json` file.
+If you already have a project that you'd like to use with Guppy, you can opt to import an existing project instead. _Please be advised that this feature hasn't been rigorously tested!_ It will only work with projects created with Gatsby or create-react-app, and in the worst case it could potentially mess up your project's `package.json` file. To play it safe, make sure that your project is managed with source-control, so that you can easily reset it if anything goes wrong.
+
+For more information on the project-creation process, please see our [Adding a Project](https://github.com/joshwcomeau/guppy/blob/master/docs/adding-a-project.md) doc.
 
 ## Managing your project
 

package.json

@@ -1,10 +1,10 @@
 {
   "name": "guppy",
   "productName": "Guppy",
-  "version": "0.1.0",
+  "version": "0.0.1",
   "private": true,
   "main": "src/main.js",
-  "homepage": "https://github.com/joshwcomeau/guppy",
+  "homepage": "./",
   "repository": {
     "type": "git",
     "url": "https://github.com/joshwcomeau/guppy.git"
@@ -169,4 +169,4 @@
     "icon": null,
     "createdAt": 1529502079329
   }
-}
+}