Skip to main content

Development Guide

🐾 First Steps​

  1. Create an account: GitHub
  2. Create an account: Discord
  3. Sign the CLA
  4. Join the Arrow Discord
    • Be sure to visit the #start-contributing channel and give yourself a role!
  5. Set up a GPG Key

🎠 Workflow​

📍 Claim a Task​

  1. Visit the Arrow Dework
    • Sign in with your Discord credentials
  2. View open tasks
    • Dework - Open Tasks
  3. Claim a task, easy as a button click!
    • Dework - Claim Task
    • Some important tasks are by application only. Describe why you're a good fit for the task!

🔧 Work on a Task or Subtask​

❗ See our Git Guidelines

  1. Clone or fork the target repository.
  2. Create a branch.
  3. Code!
  4. ❗ Sign ❗ your changes and push to the remote.
    • Commits to all remote branches must be signed
    • See Sign Your Commits for instructions on setting up a GPG Key
    • Use the -S option to sign your commits
      • git commit -S -m "Add README.md"

🏁 Push Changes​

  1. Make a pull request targeting the develop branch
    • A "Pull Request" is a public request to merge your branch into another branch
    • If making edits to the website, seek to merge your PR into the website staging branch instead.
    • main is our latest stable release. develop is merged into main at the end of every release.
    • How to create a pull request from a fork.
  2. Confirm the presence of the cla-signed label.
    • If you haven't signed the CLA, the cla-bot will be disappointed 😠
  3. Confirm that the GitHub Actions checks pass.
    • These checks will vary from repository to repository
    • GitHub - Checks
  4. Get approvals!
    • The number of approvals may vary from repo to repo.
    • Approvals generally need to come from core members of the Arrow teams.
  5. Merge!

⚡ VS Code Extensions​

These extensions are recommended:

# In VS Code Quick Open (Ctrl+P)
ext install \
bierner.github-markdown-preview \
rust-lang.rust-analyzer \
ms-python.python \
docsmsft.docs-yaml \
njpwerner.autodocstring \
stkb.rewrap \
eamodio.gitlens \
ms-vscode-remote.vscode-remote-extensionpack \
tamasfe.even-better-toml \
EditorConfig.EditorConfig \
zxh404.vscode-proto3 \
4ops.terraform \
  • GitHub Markdown Preview
    • Includes mermaid (uml) rendering and emoji rendering in markdown preview pane
  • rust-analyzer
    • Linting, "go to" support, types and docs on hover, etc.
  • Python
    • Syntax highlighting, linting, intellisense
  • docs-yaml
    • Intellisense, validation for YAML files
  • Even Better TOML
    • TOML files are used for Rust configuration
    • Validation, syntax highlighting
  • autoDocstring
    • Python docstring generator
  • Rewrap
    • Wrap code comments to fit within n characters
    • Need to enable this in Preferences->Settings->type "Rewrap"
    • 80 characters is the recommended column
  • GitLens
    • Hover over lines to see commit history, last author
  • Remote Development
    • For working over SSH
  • EditorConfig
    • Override user/workspace settings with settings found in .editorconfig files.
  • VS Code Proto3
    • Syntax highlighting for .proto files
  • Terraform
    • Syntax highlighting for .tf files

🚧 Git Guidelines​

🌳 Branches​

Use the suggested Dework Task branch name.

Dework - Suggested Git Branch Name

  • e.g. am-smith/dw-227/rust-service-template
  • This links your work to a ticket
  • Closing a pull request with this branch will also mark the Dework task as "Done"!
  • Subtasks have their own branch names. Click on the subtask first to open up the subtask menu.

🔏 Sign Your Commits​

We enforce signed commits to authenticate commits from an author.

❗ All remote branches are protected from unsigned commits through GitHub repository settings.

Setting up a GPG Key:

Add an -S to your commit command to sign it, e.g. git commit -S -m "Add README.md".

💬 Commit Messages​

As described here:

  • Message should be in present tense (Add new feature instead of Added new feature)
    • Should be written as if giving a command or instruction (Remove bug X, Update README.md)
  • Message should start with a capital letter (Add new feature)
  • Emojis, if used, should be at the start of the message (🎉 Add new feature)

Additionally:

  • Do not exceed a line length of 50 characters for commit title
  • Do not exceed a line length of 72 characters for commit body
  • Do not end the message with a period

Keep these in mind always, especially when squashing commits (one message).

👍 Pull Requests​

  • Pull Requests should target the develop branch
    • For the website repository, target the staging branch
  • Keep PRs small and easy to review!
    • Our reviewers may ask you to divide your PR into multiple smaller PRs.
  • If the commit history is messy, recommend "Squash and Merge" when pushing in changes.
    • The squashed commit should have a thorough description of the changes added.
  • The Pull Request comments should be descriptive
    • A brief description of what was changed and why
  • Your PR should equate to no more than one Dework issue
    • Addressing multiple tickets in one merge makes it harder to debug breaking changes.
    • Use git commit --fixup <commit sha> to fix a previous commit.

📚 Repositories (Create, Modify, Delete)​

Repositories are managed through Terraform.

Requests for repository management should be made to @owlot.

🔨 Makefile and build automation​

All Arrow GitHub repositories are started from templates and are provisioned by Terraform to automate changes in the workflow. Templates contain a Makefile which is propagated to all repositories.

Each repository has a Makefile which uses make utility to run build targets. All make targets call specific commands from a docker container arrow-rust. Arrow-rust is a docker image with all the tools needed to build and test Rust code so developers don't have to install them locally.

  • they can be run separately - e.g. make cspell-test.
  • or multiple targets can be run at once. This is done during pre-commit hooks or PR checks. - make test.
  • or all targets to run test, build and release phases - make all.

Makefile targets​

Run make help to see all available targets or explore template Makefile and linked Makefiles.

🔐 Admin Access​

Elevated access to our various team platforms is limited.

Ping @thomasg or @owlot and describe what you want to do.