diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index eff683a9..9908ccae 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,16 +14,15 @@ jobs: - uses: extractions/setup-just@v1 - - uses: Roblox/setup-foreman@v3 + - uses: Roblox/setup-foreman@v1 with: token: ${{ secrets.GITHUB_TOKEN }} - allow-external-github-orgs: true - - run: just init - - run: just lint + - name: Initialize the project + run: just init - - name: Lint file extensions - run: ./bin/lint.sh + - name: Lint + run: just lint - name: Get model file name run: | @@ -46,13 +45,15 @@ jobs: - uses: extractions/setup-just@v1 - - uses: Roblox/setup-foreman@v3 + - uses: Roblox/setup-foreman@v1 with: token: ${{ secrets.GITHUB_TOKEN }} - allow-external-github-orgs: true - - run: just init - - run: just analyze + - name: Initialize the project + run: just init + + - name: Run Luau analysis + run: just analyze # Running unit tests in CI has historically been cumbersome, and presently # there is no way to run Roblox Studio from a GitHub workflow. As such, our diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 00000000..9be45fc2 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,9 @@ +{ + "recommendations": [ + "evaera.vscode-rojo", + "Kampfkarren.selene-vscode", + "JohnnyMorganz.stylua", + "JohnnyMorganz.luau-lsp", + "EditorConfig.EditorConfig", + ] +} \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md index 0dfc0aca..87bf2221 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -6,55 +6,23 @@ sidebar_position: 5 Thank you for your interest in contributing to this repository! This guide will help you get your environment setup so you can have the best possible development experience. -## Getting Started +## Onboarding -You should be using [Visual Studio Code](https://code.visualstudio.com/) as your text editor, and have the following extensions installed: +We use [Visual Studio Code](https://code.visualstudio.com/) to work on this project, so you'll get the best mileage from using it too. We also have several [recommended extensions](https://github.com/flipbook-labs/flipbook/blob/main/.vscode/extensions.json) that should be installed. -- [Rojo](https://marketplace.visualstudio.com/items?itemName=evaera.vscode-rojo) -- [Selene](https://marketplace.visualstudio.com/items?itemName=Kampfkarren.selene-vscode) -- [StyLua](https://marketplace.visualstudio.com/items?itemName=JohnnyMorganz.stylua) -- [Luau LSP](https://marketplace.visualstudio.com/items?itemName=JohnnyMorganz.luau-lsp) +You will also need [Just](https://github.com/casey/just) for running commands, and [Foreman](https://github.com/Roblox/foreman/) +for installing pinned tool versions. -Once the Rojo extension is installed a welcome screen will be displayed. Scroll down to the section for the Roblox Studio plugin and select "Manage it for me." Next time you open a place in Studio you will have the Rojo plugin ready to go. - -Next install our toolchain manager, [Foreman](https://github.com/Roblox/foreman/). Foreman handles the installation of several of our other tools, like Rojo, Wally, Selene, and StyLua. - -To make the tools that Foreman installs avialable on your system you will need to manually add it to your `PATH`. - -- Windows - - Add `C:\Users\You\.foreman\bin` to your `PATH` - - Follow [this guide](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/) for how to do that -- MacOS - - Open Terminal - - Open the corresponding file for your terminal - - Bash: `nano ~/.bash_profile` - - ZSH: `nano ~/.zshenv` - - Append `export PATH="$PATH:~/.foreman/bin` to the end of the file - -## Development - -With the above requirements satisfied, run the following commands from your clone of this repository to start developing: +With the above requirements satisfied, run the following commands from your clone of the repo to start developing: ```sh -# Install Rojo, Wally, Selene, StyLua, and others -foreman install +# Install tools and packages that the project depends on +just init -# Install dependencies -wally install +# Build the plugin to Studio +just build ``` -Next use Rojo to build the plugin: - -```sh -# Windows -rojo build dev.project.json -o $LOCALAPPDATA/Roblox/Plugins/flipbook.rbxm - -# MacOS -rojo build dev.project.json -o ~/Documents/Roblox/Plugins/flipbook.rbxm -``` - -You can also run `rojo build` with the `--watch` flag while developing so that the plugin gets rebuilt when changes are made. Once rebuilt, simply reload to a new Baseplate for the changes to take effect. - :::tip When using VSCode, you can press `Ctrl+Shift+B` on Windows or `Cmd+Shift+B` on MacOS to execute the included build task which will build the flipbook plugin for your OS. ::: diff --git a/justfile b/justfile new file mode 100644 index 00000000..2098d005 --- /dev/null +++ b/justfile @@ -0,0 +1,76 @@ +#!/usr/bin/env just --justfile + +project_name := "flipbook" +plugins_dir := if os_family() == "unix" { + "$HOME/Documents/Roblox/Plugins" +} else { + "$LOCALAPPDATA/Roblox/Plugins" +} +plugin_path := plugins_dir / project_name + ".rbxm" + +project_dir := absolute_path("src") +example_dir := absolute_path("src") +packages_dir := absolute_path("Packages") +tests_project := "tests.project.json" + +tmpdir := `mktemp -d` +global_defs_path := tmpdir / "globalTypes.d.lua" +sourcemap_path := tmpdir / "sourcemap.json" + +client_settings := "/Applications/RobloxStudio.app/Contents/MacOS/ClientSettings" + +_lint-file-extensions: + #!/usr/bin/env bash + set -euo pipefail + files=$(find {{ project_dir }} {{ example_dir }} -iname "*.lua") + if [[ -n "$files" ]]; then + echo "Error: one or more files are using the '.lua' extension. Please update these to '.luau' and try again" + echo "$files" + exit 1 + fi + +default: + @just --list + +wally-install: + wally install + rojo sourcemap {{ tests_project }} -o {{ sourcemap_path }} + wally-package-types --sourcemap {{ sourcemap_path }} {{ packages_dir }} + +init: + foreman install + just wally-install + +lint: + selene {{ project_dir }} + stylua --check {{ project_dir }} + just _lint-file-extensions + +build: + rojo build -o {{ plugin_path }} + +build-watch: + npx -y chokidar-cli "{{ project_dir }}/**/*" --initial \ + -c "just build" \ + +set-flags: + mkdir -p {{ client_settings }} + cp -R tests/ClientAppSettings.json {{ client_settings }} + +test: + just set-flags + rojo build {{ tests_project }} -o test-place.rbxl + run-in-roblox --place test-place.rbxl --script tests/run-tests.lua + +analyze: + curl -s -o {{ global_defs_path }} \ + -O https://raw.githubusercontent.com/JohnnyMorganz/luau-lsp/master/scripts/globalTypes.d.lua + + rojo sourcemap {{ tests_project }} -o {{ sourcemap_path }} + + luau-lsp analyze --sourcemap={{ sourcemap_path }} \ + --defs={{ global_defs_path }} \ + --settings="./.vscode/settings.json" \ + --ignore=**/_Index/** \ + {{ project_dir }} +