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:
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.
Below are some rules to follow when working with a version control system such as Git:
Broken code should not be committed.
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
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
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
- Separate subject from body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line
- Do not end the subject line with a period
- Use the imperative mood in the subject line
- Wrap the body at 72 characters
- Use the body to explain what and why vs. how
- A collection of useful .gitignore templates
- The Ignoring Files chapter of the Pro Git book.
- The Ignoring Files article on the GitHub Help site.
- The gitignore(5) manual page.
- GitHub: Creating Releases
- Drupal: Release Types
- Drupal: Release - rc, alpha, beta, dev
- Drupal: Release Naming Conventions
- StackOverflow: Release Title is Same as Release Version
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
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.
Self describing, terse code should be the norm. But, often times the complexity ....
- Check what packages are available before development. http://www.ros.org/browse/list.php
- Packages vs Nodes
- Standard Units of Measure and Coordinate Conventions
- Dynamixel
- Standard servo