Skip to content

Latest commit

 

History

History
executable file
·
252 lines (165 loc) · 9.34 KB

COLLABORATE.md

File metadata and controls

executable file
·
252 lines (165 loc) · 9.34 KB
Raw

Collaborating

Summary

DATRO's website, document, software and training video source-code (everything) is held in a single public repository ("monorepo") The primary location of this monorepo is github.com/unclehowell/datro. But it can be discovered elsewhere online and offline - just ask around. There's a few branches in the monorepo e.g. gh-pages, netlify, subrepos etc This branch is entitled 'net-installer' - since it primarily contains the source for net-installers. Net-Installers autonomously self-build a disk image, including the devices firmware and software.

Why Collaborate

Unlike other open source projects, it's worth collaborating since DATRO distributes its network revenue between developers fully autonomously. Since developers maintain, own and control their contributing source code, beneficial interest in this network is managed as an ongoing royalty.

Basic Concept

  1. You make your own github repository (name it with relivance to the content). Your contribution, so you'll maintain ownership and control.
  2. You make a seperate branch and entitle it 'hotspotbnb', then add your cryptocurrency wallets (so our blockchain smart contracts know who to pay).
  3. Next you propose a small modification to our source code to included your repo as a subrepo within ours:
  • Without this method of subrepos payment to the owners of valid, concurrent software dependancies can't be automated or assured.
  • We'd also otherwise risk successful autonomous system builds and user experience, if the 3rd party deletes their repo on any given sunday.
  1. If your proposed changes are accepted by our moderator(s) you'll see your source code in the next release.
  2. Any changes you want to make to your source code thereafter, you make it your repo and the subrepo link will notify us.
  3. Vice versa, any changes made to your sub-repo in our source code, notifies you via your repo.

This whole method of collaboration and payment helps us carefully migrate towards becoming a DAO. Assessing each risk and tackling each challenge one step at a time to avoid exposures to modern cyber-threats and other vunerabilities.

Symantic Version Control

See the CHANGELOG file for more information

Exceptions when COLLABORATING

  1. CHANGELOG - Self explanitory when you look at the changelog. But look carefully as we combine Prince2 and Semver.
  2. Semantic Versioning (this branch only)
  • 'net-installer' branch gets the mighty RC (Release Candidate) suffix in its version release number e.g. x.x.x-rc.x
  • the other branches are all websites and docs. This branch contains the actual (uncompiled) software e.g. software source code.

Get Started

  1. Although you can clone the monorepo to your local machine, it's massive. So we suggest sparse-checkout - instructions to follow.
  2. We suggest you make your proposed changes locally, on your own branch name, then submit changes accordingly.

GitHub 'mono' Repo

This collaboration guide focuses on two key ways of interacting with this monorepo branch:

1. Sparse-checkout:

  • since the monorepo is so big and diverse, collaborators should only checkout and push back directories they're actively working on
  • the sparse-checkout method is designed for this purpose, making it the ideal choice

2. Git Pull

  • standard practice with github, but in light of how massive the monorepo is huge you're better off getting familiar with method 1

Before Getting Stuck-In

This monorepos branches can be retrieved (download only, in its entirety, via github.com) or using a command-line method called Subversions:

  • Subversions are used in the scripts in the firmware (v0.0.1-rc.6+). Depends on the 'subversion' package being installed
  • svn (or svn co subversion checkout) appears to be the cleanest way of downloading (download-only) specific folders
  • If you're a super freak when it comes to github, you can even grab earlier commits, which may exclude developments and direction, you may not wish to build upon or follow A great example of this is when Emby made IPTV a paid feature, so developed branched off (using an earlier version), calling it Jellyfin Now all the cheapskates get to continue enjoying their media center, with free IPTV - it's just called Jellyfin now.

Getting Started with Sparse Checkout

  1. Make sure your version of Git is up to date (2.25.0+), or sparse-checkout will fail:

    sudo apt update && apt upgrade -y

add-apt-repository ppa:git-core/ppa

apt update

apt install git

  2. Create a local directory to store your copy of this monorepo:

    # xxx symbolises the name of your local copy

mkdir xxx

# enter into the directory you just created

cd xxx

  3. Initiate the folder as a new, empty, local git repository:

    # rm -rf .git undoes the following command (useful after you've got a subdirectory you don't plan on modifying or uploading back to GitHub)

git init

  4. Stage the repo ready for fetching, but remotely:

    # leave the *.git off the end to get the README.md and CHANGELOG.md files

git remote add origin https://github.com/unclehowell/HBnB.git

  5. Checkout files and give your branch a name:

    # create a branch name to summarise your changes

git checkout -b 'BRANCH-NAME'

  6. Restrict git to only get the directory/subdirectory you need:

  • Custom configuration method:

    # enable sparse-checkout

git config core.sparsecheckout true

# specify directory/subdirectory you want to work on (in lowercase)

git sparse-checkout set TOPLEVELDIRECTORY/SUBDIRECTORY

# e.g. web/ makes .git/info/sprase-checkout look like this:
  /*
  !/*/
  /web/

  • Some genius baked up a solution to automate the above step:

    # get our shell script, set the permissions and run it

wget https://raw.githubusercontent.com/unclehowell/HBnB/master/checkout.sh && chmod +x checkout.sh

./checkout.sh # followed by the name of the topleveldirectory you want e.g. web, service, client or docs

# remove this file once you've run in or the next step will fail
# don't worry, as soon as you pull (next step) the file comes back

rm -r checkout.sh

  1. Now proceed to actually retrieve the files you want on your local machine:

    # git fetch maybe more appropriate than git pull - be wise!

git chechout -b 'YOUR BRANCH NAME'

  2. Make your edits, bug fixes, enhancements etc ... TAKE NOTE: Here's how you checkout extra folders you may need, while you're working:

    git read-tree -mu HEAD
git pull origin master
git config core.sprasecheckout true
git pull origin master
git sparse-checkout set FOLDER1 FOLDER2 FOLDER3 etc

  3. Once completed with your changes, you'll want to run 'git add'

    # first run a pull again, incase there's been some changes

git pull origin 'BRANCH NAME'

git add ./

  4. Next commit with a brief summary of your changes

    #
git commit -m "BRIEF SUMMARY OF YOUR CHANGES"

  5. Then 'git push' to push your branch to GitHub

    #
 git push origin 'YOUR-BRANCH-NAME'

  6. Finally make a pull request, so the administrator of the project can review your changes and merge your branch into the master branch of this proje

GitHub will notify you if there's a comment to respond to or when the administrator has processed the merge.

Getting Started with Sub Repos

  1. Create and execute a script to install the subrepo command:

    # make a file called install-git-subrepo.sh
 touch install-git-subrepo.sh

# use nano to edit the file `sudo nano` and past the following and save the file:
sudo apt-get update \
  && apt-get install -y --no-install-recommends \
     less \
     git

git clone --depth=1 --branch=0.3.1 https://github.com/ingydotnet/git-subrepo.git /tmp/git-subrepo \
   && cd /tmp/git-subrepo \
   && make install \
   && cd - \
   && rm -rf /tmp/git-subrepo

# make the file executable and run it
sudo chmod +x install-git-subrepo.sh && ./install-git-subrepo.sh

# any issues, look for support here https://github.com/ingydotnet/git-subrepo

    Handy Commands

    Change permission of all files in the repo.

    Handy when your text editor software (atom/ notepad C++) can't save changes

    find /xxxx/xxxx -type f -exec chown user:user {} \; # f is folder, use d for directories

    When you just need a bunch of files in a repo (no pull, sparse-checout - just files, quick and dirty)

    svn co --depth files https://github.com/unclehowell/datro/branches/gh-pages/static/gui/dashboard/img/

    This code bulk changes the extension on multiple files

    #!/bin/sh

    for i in *.txt do mv -- "$i" "${i%.txt}" done

    Command for finding text in all files in a specific directory

    grep -rnw '/path/to/somewhere/' -e 'pattern'