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​

❗ 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 the 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.
  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 \
  • 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

🚧 Git Guidelines​

🌳 Branches​

The branch name should be copied from a Arrow DeWork task.

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"!

🔏 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​

  • 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 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.

🔐 Admin Access​

Elevated access to our various team platforms is limited.

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