Provide development setup instructions

[ronaldtse]

Requested by @strogonoff . FYI @CAMOBAP .

Courtesy of DeepSeek:

Comprehensive Guide for Setting Up Ruby and Metanorma Flavors
For macOS, Linux, and Windows (PowerShell/CMD)

---

1. Prerequisites

• macOS/Linux:
  • Xcode Command Line Tools (macOS) or build-essential (Linux).
  • Git installed.
• Windows:
  • RubyInstaller: Download the [Ruby+Devkit](https://rubyinstaller.org/) for your Ruby version (e.g., 3.2.2).
  • Git for Windows: Install from [git-scm.com](https://git-scm.com/).

---

2. Install Ruby

macOS/Linux (Using asdf)

1. Install asdf (version manager):

   # macOS with Homebrew
   brew install asdf
   echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ~/.zshrc  # or ~/.bashrc
   
   # Linux
   git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0
   echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
   source ~/.bashrc

2. Install Ruby:

   asdf plugin add ruby
   asdf install ruby 3.2.2  # Replace with your version
   asdf global ruby 3.2.2

Windows (Using RubyInstaller)

1. Run the RubyInstaller executable.
   • Check “Add Ruby to PATH” during installation.
2. After installation, a CMD window will open to install the MSYS2 Devkit. Press Enter to proceed.
3. Verify in PowerShell:

   ruby -v  # Check Ruby version
   gem -v   # Check RubyGems version

---

3. Install Bundler

All Platforms:

# macOS/Linux (Terminal) or Windows (PowerShell)
gem install bundler

---

4. Fork and Clone Repositories

1. Fork repositories on GitHub (e.g., metanorma/metanorma, metanorma/mn-samples-iso).
2. Clone your fork locally:

   # Windows (PowerShell)
   git clone https://github.com/your-username/metanorma.git
   git clone https://github.com/your-username/mn-samples-iso.git

---

5. Configure Gemfile for Local Development

Edit the Gemfile in your flavor repository (e.g., mn-samples-iso) to use local gems:

# Replace:
# gem "metanorma-iso", github: "metanorma/metanorma-iso"

# With:
gem "metanorma-iso", path: "../metanorma-iso"  # Use forward slashes on Windows

Install Dependencies:

# Navigate to your flavor repo
cd mn-samples-iso

# Install gems (macOS/Linux/WSL: use bundle; Windows: same command)
bundle install

---

6. Testing Workflow

1. Make changes to your local gem (e.g., metanorma-iso).
2. Update dependencies in the flavor repo:

   bundle update metanorma-iso

3. Run tests:

   # In the gem repo (e.g., metanorma-iso)
   bundle exec rspec

4. Generate documents:

   # In the flavor repo (e.g., mn-samples-iso)
   bundle exec metanorma site generate

---

7. Submitting Pull Requests

1. Commit changes to your gem:

   git checkout -b my-feature
   git add .
   git commit -m "Add feature"
   git push origin my-feature

2. Create a PR on GitHub from your fork to the upstream repository.
3. Revert the Gemfile in the flavor repo before finalizing the PR:

   gem "metanorma-iso", github: "metanorma/metanorma-iso"

---

Windows-Specific Notes

• Path Format: Use forward slashes (/) in Ruby paths, even on Windows.
• Line Endings: Configure Git to avoid CRLF issues:

  git config --global core.autocrlf false

• Native Gems: Ensure the MSYS2 Devkit (installed via RubyInstaller) is available for compiling extensions.
• PowerShell: Use it instead of CMD for better scripting compatibility.

---

Troubleshooting

• Gem Installation Failures:
  • Run ridk enable (from RubyInstaller) to configure MSYS2.
  • Install missing DLLs via pacman -S mingw-w64-x86_64-toolchain in the MSYS2 shell.
• Path Issues: Verify Ruby is in your PATH:

  $env:Path -split ";" | Select-String "Ruby"

---

This workflow ensures cross-platform compatibility, with Windows users leveraging RubyInstaller for native development. For fewer issues, consider WSL for Unix-like tooling. Let me know if you need further refinements! 🛠️

Originally posted by @ronaldtse in #953