Development Guide
🐾 First Steps
- Create an account: GitHub
- Create an account: Discord
- Sign the CLA
- Join the Arrow Discord
- Be sure to visit the
#start-contributing
channel and give yourself a role!
- Be sure to visit the
- Set up a GPG Key
- See Sign Your Commits for instructions
🎠 Workflow
📍 Claim a Task
- Visit the Arrow Dework
- Sign in with your Discord credentials
- View open tasks
- Claim a task, easy as a button click!
- 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
- Clone or fork the target repository.
- If you are not a core member of an Arrow GitHub team, you will need to work from a fork.
- How to Fork a Repository
- Create a branch.
- Our branch names are generated by Dework! See our branch guidelines.
- Code!
- Be sure to follow our Code Style Guides!
- ❗ 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 commitsgit commit -S -m "Add README.md"
🏁 Push Changes
- 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 intomain
at the end of every release.- How to create a pull request from a fork.
- Confirm the presence of the
cla-signed
label.- If you haven't signed the CLA, the cla-bot will be disappointed 😠
- Confirm that the GitHub Actions checks pass.
- These checks will vary from repository to repository
- Get approvals!
- The number of approvals may vary from repo to repo.
- Approvals generally need to come from core members of the Arrow teams.
- 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
- Includes
- 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.
- Override user/workspace settings with settings found in
- VS Code Proto3
- Syntax highlighting for
.proto
files
- Syntax highlighting for
- Terraform
- Syntax highlighting for
.tf
files
- Syntax highlighting for
🚧 Git Guidelines
🌳 Branches
Use the suggested Dework Task 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.
- Security, accountability, traceability
- "How (and why) to sign Git commits" - Alessandro Segala
❗ All remote branches are protected from unsigned commits through GitHub repository settings.
Setting up a GPG Key:
- Generate a GPG Key
- Informing Git about your GPG Key
- Informing GitHub about your GPG Key
- All commits signed by default:
git config --global commit.gpgsign true
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
- For the website repository, target the
- 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.