Understanding ArduSub GitHub - Custom Frame

Blue Robotics Software ArduSub
, ,
5

This is mostly git and semver (semantic versioning) fundamentals rather than ArduSub-specific, but happy to clarify:

  • github.com/ArduPilot/ardupilot is a remote repository, that’s part of and owned by the ArduPilot project, and is where contributions get merged and shared (by anyone, for everyone)
    • it has several branches of code development, including
      • master, where all the latest changes get merged in (if you flash ‘development’ firmware, that’s generated directly and automatically from the master branch - it can change significantly and frequently, without warning, so we generally recommend against using it unless you’re an active developer of the firmware)
      • Sub-4.0, where ArduSub version 4.0 maintenance is done (ArduSub 4.0.x releases get made from this branch)
      • Sub-4.1, where ArduSub version 4.1 beta testing is being done (ArduSub ‘Beta’ releases are currently made from this branch)
    • it has several tags/releases that demarcate a particular point in development, including
      • ArduSub-4.0.2, which is a specific patch of ArduSub version 4.0
      • ArduSub-4.0.3, which is a more recent patch of ArduSub version 4.0
      • ArduSub-stable, which we update to be in line with the latest stable patch of ArduSub (currently 4.0.3, but at some point will move to 4.1.0, for example)
      • ArduSub-beta, which we update to be in line with the latest beta/testing code of ArduSub (currently version 4.1, but at some point will move to 4.2 once 4.1 becomes the new “stable”)
    • it is the upstream/parent remote of forks, when people want their own version of the repository
  • github.com/your-user-id/ardupilot is your remote repository (to do what you want with), which is forked from the main ArduPilot/ardupilot repository (it knows where it came from)
    • by default it contains the same branches as the ArduPilot/ardupilot repository (from the point in time when you made the fork), but
      • you can fetch and merge updates to branches from the parent repository
      • you can add your own new branches, to branch off from any commit (point in history) in an existing branch (recommended before making any changes, to keep the “update from parent” process clean, and to keep your changes separate/isolated - changes can be rebased onto an updated parent)
      • you can remove branches (your own or otherwise) if you want to
    • if you make changes you think should be included in the main repository
      • you can submit a pull request from one of your branches to the master branch in the parent repo
      • which will then be reviewed by other ArduPilot developers, and potentially merged in
      • see the contributing guidelines for more info
    • by default it contains the same tags/releases as the parent repository (from when you forked it), but
      • you can fetch new/updated tags/releases from upstream
      • you can make your own tags/releases (generally not required, unless you or others are actively using multiple versions of your code, and need some of them to be extra user-friendly to install/use, which is usually grounds for it to be part of the parent repository instead)
    • GitHub allows you to edit files directly, but
      • that’s generally only used for small changes/documentation
      • it’s harder to keep a clean history
      • outside of continuous integration tools, you can’t do much with the files on GitHub
  • git clone <repo> clones (copies) a remote repository (from the place you specified) into a local one, on the computer you’re cloning with
    • if the remote is on another computer (e.g. a url from the internet) it will be downloaded
    • you can make and commit (save, in history) changes in your local repository
    • you can use the code to do things (e.g. you can run the install prereqs script, and build/compile ArduSub from your local repository)
    • you can pull (fetch and merge) changes from a remote repository
    • you can push changes to your remote repository (to back them up, and if it’s an online remote like github it can be shared with others)

Accordingly,

  • AP_Motors6DOF.cpp should be modified in your own branch, in the local repository on your computer
  • it’s recommended to create multiple branches if you want to keep track of and try multiple configurations, so that you can easily switch between them (with checkout)
  • you can commit a change if you want to save it for later
  • you can push commits to your own remote (assuming you cloned from your remote, and not the ArduPilot one) if you want to share them with others (including yourself on another computer)
  • you do the setup of cloning, checkout, installing prerequisites, and configuring waf once per computer
    • the checkout can be of your own branch if you’ve pushed it to your remote, instead of making a new branch and re-doing your changes every time
  • you compile ArduSub on your computer, using ./waf sub in your local repository (with your changes in it)
    • this is the only step that needs to happen again when you’ve made changes on the same computer
    • you may need to configure waf again if you change board types at some point

I understand I may have slightly confused you by putting the clone in my example instructions from the ArduPilot/ardupilot repo instead of from your own one. I’ve edited my comments to specify your one instead.

Note also that, as mentioned, the tag is fixed now, so it’s better to checkout from the ArduSub-stable tag rather than the Sub-4.0 branch (good to get in the habit of using the reference that we keep updated as the recommended place to work from). Follow the normal instructions (summarised in my second comment), rather than the workaround I suggested in my first comment.