v0.2.3

* Roact
* Rodux
* RoactRodux
* TestEZ

.gitmodules

@@ -0,0 +1,12 @@
+[submodule "modules/Roact"]
+	path = modules/Roact
+	url = https://github.com/Roblox/Roact.git
+[submodule "modules/Rodux"]
+	path = modules/Rodux
+	url = https://github.com/Roblox/Rodux.git
+[submodule "modules/RoactRodux"]
+	path = modules/RoactRodux
+	url = https://github.com/Roblox/RoactRodux.git
+[submodule "modules/TestEZ"]
+	path = modules/TestEZ
+	url = https://github.com/Roblox/TestEZ.git

CHANGES.md

@@ -3,6 +3,15 @@
 ## Current Master
 * *No changes*
 
+## 0.2.3
+* Plugin only release
+* Tightened `init` file rules to only match script files
+	* Previously, Rojo would sometimes pick up the wrong file when syncing
+
+## 0.2.2
+* Plugin only release
+* Fixed broken reconciliation behavior with `init` files
+
 ## 0.2.1
 * Plugin only release
 * Changes default port to 8000

README.md

@@ -3,53 +3,37 @@
 	<a href="https://travis-ci.org/LPGhatguy/Rojo">
 		<img src="https://api.travis-ci.org/LPGhatguy/Rojo.svg?branch=master" alt="Travis-CI Build Status" />
 	</a>
-	<a href="#">
-		<img src="https://img.shields.io/badge/docs-soon-red.svg" alt="Documentation" />
-	</a>
 </div>
 
 <div>&nbsp;</div>
 
-**EARLY DEVELOPMENT, USE WITH CARE**
+Rojo is a flexible multi-tool designed for creating robust Roblox projects. It's in early development, but is still useful for many projects.
 
-Rojo is a flexible multi-tool designed for creating robust Roblox projects.
+It's designed for power users who want to use the **best tools available** for building games, libraries, and plugins.
 
-It's designed for power users who want to use the best tools available for building games, libraries, and plugins.
+## Features
 
-It has a number of desirable features *right now*:
+Rojo has a number of desirable features *right now*:
 
-* Work from the filesystem, in your favorite editor
+* Work on scripts from the filesystem, in your favorite editor
 * Version your place, library, or plugin using Git or another VCS
 
 Soon, Rojo will be able to:
 
+* Sync Roblox objects (including models) bi-directionally between the filesystem and Roblox Studio
 * Create installation scripts for libraries to be used in standalone places
 	* Similar to [rbxpacker](https://github.com/LPGhatguy/rbxpacker), another one of my projects
 * Add strongly-versioned dependencies to your project
 
 ## Installation
 Rojo has two components:
-* The binary, written in Rust
+* The command line tool, written in Rust
 * The [Roblox Studio plugin](https://www.roblox.com/library/1211549683/Rojo-v0-0-0), written in Lua
 
-To install the binary, there are two options:
-* Cargo, which requires you to have Rust installed
-* Pre-built binaries from the [the GitHub releases page](https://github.com/LPGhatguy/rojo/releases)
-
-### Cargo (Recommended)
-Make sure you have [Rust 1.21 or newer](https://www.rust-lang.org/) installed.
-
-Install Rojo using:
-
-```sh
-cargo install rojo
-
-# Installed!
-rojo help
-```
-
-### Pre-Built (Windows only)
-Download the latest binary from [the GitHub releases page](https://github.com/LPGhatguy/rojo/releases). Put it somewhere you can access it from a terminal!
+To install the command line tool, there are two options:
+* Cargo, if you have Rust installed
+	* Use `cargo install rojo` -- Rojo will be available with the `rojo` command
+* Download a pre-built Windows binary from [the GitHub releases page](https://github.com/LPGhatguy/rojo/releases)
 
 ## Usage
 For more help, use `rojo help`.
@@ -66,8 +50,92 @@ rojo init
 
 Rojo will create an empty project in the directory.
 
+The default project looks like this:
+
+```json
+{
+  "name": "my-new-project",
+  "servePort": 8000,
+  "partitions": {}
+}
+```
+
+### Start Dev Server
+To create a server that allows the Rojo Dev Plugin to access your project, use:
+
+```sh
+rojo serve
+```
+
+The tool will tell you whether it found an existing project. You should then be able to connect and use the project from within Roblox Studio!
+
 ### Migrating an Existing Roblox Project
-Coming soon!
+**Coming soon!**
+
+### Syncing into Roblox
+In order to sync code into Roblox, you'll need to add one or more "partitions" to your configuration. A partition tells Rojo how to map directories to Roblox objects.
+
+Each entry in the partitions table has a unique name, a filesystem path, and the full name of the Roblox object to sync into.
+
+For example, if you want to map your `src` directory to an object named `My Cool Game` in `ReplicatedStorage`, you could use this configuration:
+
+```json
+{
+  "name": "rojo",
+  "servePort": 8000,
+  "partitions": {
+    "game": {
+      "path": "src",
+      "target": "ReplicatedStorage.My Cool Game"
+    }
+  }
+}
+```
+
+The `path` parameter is relative to the project file.
+
+The `target` starts at `game` and crawls down the tree. If any objects don't exist along the way, they'll be created as `Folder` instances.
+
+Run `rojo serve` in the directory containing this project, then press the "Sync In" or "Toggle Polling" buttons in the Roblox Studio plugin to move code into your game.
+
+### Sync Details
+The structure of files and folders on the filesystem are preserved when syncing into game.
+
+Creation of Roblox instances follows a simple set of rules. The first rule that matches the file name is chosen:
+
+| File Name      | Instance Type  | Notes                                     |
+| -------------- | -------------- | ----------------------------------------- |
+| `*.server.lua` | `Script`       | `Source` will contain the file's contents |
+| `*.client.lua` | `LocalScript`  | `Source` will contain the file's contents |
+| `*.lua`        | `ModuleScript` | `Source` will contain the file's contents |
+| `*`            | `StringValue`  | `Value` will contain the file's contents  |
+
+Any folders on the filesystem will turn into `Folder` objects unless they contain a file named `init.lua`, `init.server.lua`, or `init.client.lua`. Following the convention of Lua, those objects will instead be whatever the `init` file would turn into.
+
+For example, this file tree:
+
+* my-game
+	* init.client.lua
+	* foo.lua
+
+Will turn into this tree in Roblox:
+
+* `my-game` (`LocalScript` with source from `my-game/init.client.lua`)
+	* `foo` (`ModuleScript` with source from `my-game/foo.lua`)
+
+## Inspiration
+There are lots of other tools that sync scripts into Roblox, or otherwise work to improve the development flow outside of Roblox Studio.
+
+Here are a few, if you're looking for alternatives or supplements to Rojo:
+* [Studio Bridge by Vocksel](https://github.com/vocksel/studio-bridge)
+* [RbxRefresh by Osyris](https://github.com/osyrisrblx/RbxRefresh)
+* [RbxSync by evaera](https://github.com/evaera/RbxSync)
+* [CodeSync](https://github.com/MemoryPenguin/CodeSync) and [rbx-exteditor](https://github.com/MemoryPenguin/rbx-exteditor) by [MemoryPenguin](https://github.com/MemoryPenguin)
+* [rbxmk by Anaminus](https://github.com/anaminus/rbxmk)
+
+I also have a couple tools that Rojo intends to replace:
+* [rbxfs](https://github.com/LPGhatguy/rbxfs), which has been deprecated by Rojo
+* [rbxpacker](https://github.com/LPGhatguy/rbxpacker), which is still useful
 
 ## License
 Rojo is available under the terms of the MIT license. See [LICENSE.md](LICENSE.md) for details.

plugin/.luacheckrc

@@ -51,6 +51,6 @@ files["**/*.server.lua"] = {
 	std = "+plugin",
 }
 
-files["**/*-spec.lua"] = {
+files["**/*.spec.lua"] = {
 	std = "+testez",
 }

plugin/src/Config.lua

@@ -1,4 +1,5 @@
 return {
 	pollingRate = 0.3,
-	version = "0.2.1",
+	version = "v0.2.3",
+	dev = false,
 }

plugin/src/Main.server.lua

@@ -8,7 +8,9 @@ local Config = require(script.Parent.Config)
 local function main()
 	local pluginInstance = Plugin.new()
 
-	local toolbar = plugin:CreateToolbar("Rojo Plugin v" .. Config.version)
+	local displayedVersion = Config.dev and "DEV" or Config.version
+
+	local toolbar = plugin:CreateToolbar("Rojo Plugin " .. displayedVersion)
 
 	toolbar:CreateButton("Test Connection", "Connect to Rojo Server", "")
 		.Click:Connect(function()

plugin/src/Plugin.lua

@@ -19,7 +19,7 @@ Plugin.__index = Plugin
 
 function Plugin.new()
 	local address = "localhost"
-	local port = 8000
+	local port = Config.dev and 8001 or 8000
 
 	local remote = ("http://%s:%d"):format(address, port)
 

plugin/src/Reconciler.lua

@@ -1,13 +1,27 @@
 local Reconciler = {}
 
+--[[
+	The set of file names that should pass as init files
+	These files usurp their parents.
+]]
+local initNames = {
+	["init.lua"] = true,
+	["init.server.lua"] = true,
+	["init.client.lua"] = true,
+}
+
 local function isInit(item, itemFileName)
 	if item and item.type == "dir" then
 		return
 	end
 
-	return not not itemFileName:find("^init%.")
+	return initNames[itemFileName] or false
 end
 
+--[[
+	Determines if the given VFS item has an init file. Yields information about
+	the file.
+]]
 local function findInit(item)
 	if item.type ~= "dir" then
 		return nil, nil
@@ -22,6 +36,12 @@ local function findInit(item)
 	return nil, nil
 end
 
+--[[
+	Given a VFS item, returns a Name and ClassName for a corresponding Roblox
+	instance.
+
+	Doesn't take into account init files.
+]]
 local function itemToName(item, fileName)
 	if item and item.type == "dir" then
 		return fileName, "Folder"
@@ -40,6 +60,10 @@ local function itemToName(item, fileName)
 	end
 end
 
+--[[
+	Given a VFS item, assigns all relevant values (except Name!) to a Roblox
+	instance.
+]]
 local function setValues(rbx, item, fileName)
 	local _, className = itemToName(item, fileName)
 
@@ -79,6 +103,9 @@ function Reconciler._reifyShallow(item, fileName)
 	end
 end
 
+--[[
+	Construct a new Roblox instance tree that corresponds to the given VFS item.
+]]
 function Reconciler._reify(item, fileName, parent)
 	local rbx = Reconciler._reifyShallow(item, fileName)
 
@@ -164,7 +191,7 @@ function Reconciler.reconcile(rbx, item, fileName, parent)
 		for _, childRbx in ipairs(rbx:GetChildren()) do
 			-- Child was deleted!
 			if not visitedChildren[childRbx.Name] then
-				Reconciler.reconcile(childRbx, nil, nil)
+				childRbx:Destroy()
 			end
 		end
 

plugin/src/runTests.lua

@@ -0,0 +1,4 @@
+return function()
+	local TestEZ = require(script.Parent.Parent.TestEZ)
+	TestEZ.TestBootstrap:run(script.Parent)
+end

rojo.json

@@ -1,10 +1,26 @@
 {
   "name": "rojo",
-  "servePort": 8081,
+  "servePort": 8000,
   "partitions": {
-    "Rojo": {
+    "plugin": {
       "path": "plugin/src",
       "target": "ReplicatedStorage.Rojo"
+    },
+    "modules/Roact": {
+      "path": "modules/Roact/lib",
+      "target": "ReplicatedStorage.Rojo.modules.Roact"
+    },
+    "modules/Rodux": {
+      "path": "modules/Rodux/lib",
+      "target": "ReplicatedStorage.Rojo.modules.Rodux"
+    },
+    "modules/RoactRodux": {
+      "path": "modules/RoactRodux/lib",
+      "target": "ReplicatedStorage.Rojo.modules.RoactRodux"
+    },
+    "modules/TestEZ": {
+      "path": "modules/TestEZ/lib",
+      "target": "ReplicatedStorage.TestEZ"
     }
   }
 }

test-folder/meh/init.lua

@@ -1 +0,0 @@
--- meh/init.lua

test-project/rojo.json

@@ -0,0 +1,10 @@
+{
+  "name": "test-project",
+  "servePort": 8001,
+  "partitions": {
+    "src": {
+      "path": "src",
+      "target": "ReplicatedStorage.TestProject"
+    }
+  }
+}