Skip to content

Latest commit

 

History

History
177 lines (130 loc) · 8.5 KB

README.md

File metadata and controls

177 lines (130 loc) · 8.5 KB

Development Guidelines

Below are some development guidelines and best practices when working on OpenDive software and hardware. This doc covers general guidelines on documentation, version control, and tools.

Blockchain specific readme's can be found here:

Blockchain-specific Guidelines

Table of Contents

Using Git and GitHub

We use Git for version control system (VCS), and GitHub as the application to interact with Git and to store our repositories.
There are two way to interact with Git (i.e. commit, push, merge etc). The first one is through any command line interface (CLI). The second one is through the GitHub Desktop Application available for Windows and Mac, other applications are available but we request that our engineers use GitHub's Desktop Application.

Using a commmand line interface or GitHub's desktop application you'll be able to record your code into a repository through commmits, get the latests code changes from other teammates by pulling, and manage merging your code.

Version Control

Below are some rules to follow when working with a version control system such as Git:

1. MAKE SURE THE BUILD SUCCEEDS BEFORE COMMITTING CODE.

Broken code should not be committed.

2. CREATE FEATURE BRANCHES. ISOLATE CODE THAT WILL CREATE OR CHANGE A FEATURE.

Creating a branch does not affect other team members working on a different branch. This is desireable because a feature under development can create instability in the codebase.

Here's a reference to the branching guidelines we follow:
https://graphite.dev/guides/git-branch-naming-conventions

3. ALWAYS PULL DOWN THE LATEST CHANGES BEFORE BEGINNING TO CODE.

This means that even before you start coding, you must perform a pull. In the CLI this command is git pull origin [branch-name].
This also means that you must keep you local version of the repository up to date. This is crucial if you’re working on a feature branch that may take more than a few hours to close, don’t let your branch diverge too far from the master branch.
To elaborate if you create a feature branch called feature-1 from the develop branch, make sure the perform a pull on the develop branch daily or as needed. Below we highlight this flow through commands.

# Create a new feature branch called "feature-1" from the "develop" branch"
git checkout -b feature-1 develop
# Begin coding for sometime

# Perform a pull on develop
git pull develop

# Continue coding. Review any conflicts or merges

4. USE MEANINGFUL AND SUCCINCT GIT MESSAGES.

You are writing the commits not for yourself, rather for the rest of the team.
“A commit message shows whether a developer is a good collaborator”. A project’s long-term success rests (among other things) on its maintainability and being able to review others’ commits and pull requests with ease.
This drives efficiency.

Here's an example of adequate commit messages:

5ba3db6 Fix failing CompositePropertySourceTests
84564a0 Rework @PropertySource early parsing logic
e142fd1 Add tests for ImportSelector meta-data
887815f Update docbook dependency and generate epub
ac8326d Polish mockito usage

Git Messages

When committing code into a Git repository, you will have to write a message describing your code changes.
It is crucial that we make these messages concise and consistent. A well-crafted commit message can tell other developers right away why your code changes matter or why they took place.

Chris Beams has a great post that summarizes the importance of a well-crafted commit message, along with the rationale behind it. Below are the seven rules he writes in his post, check out his post for more information.

The seven rules of a great Git commit message

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

Gitignore

What is .gitignore?

GitHub

Software Releases

Project Naming Conventions

Different frameworks and languages have different naming conventions

NodeJS
Lowercase snakecase. E.g. OpenEra Node project:

openera-frontend/

Unity
Capital camelcase / pascalCase. E.g. OpenEra Unity plugin

OpenEraWalletPlugin

Software

One's profession should not be measured by the actions that are taken, but rather by the end-goal and the means of achieving such goal.

Anyone can program, not everyone can develop scalable, robust, and maintainable software. Let's aim for that...

You may find a list of useful books and resources here.

Styleguides

Documentation

Self describing, terse code should be the norm. But, often times the complexity ....

Dependency Management

Middleware and Frameworks

ROS

Hardware

Motors

  • Dynamixel
  • Standard servo

Tools