GitHub Project

GitHub is a web-based source code repository. It acts as a centralized location for software developers to control and manage free and open source software development. Inside GitHub, Libelium has created a project Waspmote API, the user can found this project in https://github.com/Libelium/waspmoteapi

The use of Waspmote-API GitHub Project is optional. It is great for those users who have detected some bug and want to colaborate with the Community. Also users can add their own improvements.

Important, all user that want use GitHub, must be registered in www.github.com.

This new feature is aimed at users to want improve, correct bug or add functionality to share with the community must:

• Clone the repository (to fork) to be copied to your account.

• Making changes in your copy.

• Finish issuing a pull request to the owner of the original repository.

Libelium maintenance two repositories:

• Waspmote-API repository: https://github.com/Libelium/waspmoteapi

• Waspmote-API Unstable repository: https://github.com/Libelium/waspmoteapi_unstable

Waspmote-API repository is the official version of Waspmote API. The user only have read access. Nobody can push. The repository may only be downloaded.

Waspmote-API Unstable repository is the official version of Waspmote API. Users who want to work with this repository, should clone the Waspmote-API Unestable repository. The user must work about own repository, when a user wants to share their improvements, detect and fix any errors, their must carry out a "Pull Request" about Waspmote-API Unstable.

Install Git

Windows

Download and install the last release of Git, can be found in: https://git-for-windows.github.io/

Linux

There are multiple ways of installing Git on Linux. Depending on which Linux distribution you're using and whether it provides binary packages for Git, you can either install a binary package or install from source.

• Debian/Ubuntu

$ apt-get install git-core

• Fedora

$ yum install git

• Gentoo

$ emerge –ask –verbose dev-vcs/git

• FreeBSD

$ cd /usr/ports/devel/git
$ make install

• Solaris 11 Express

$ pkg install developer/versioning/git

• OpenBSD

$ pkg_add git

Mac OS

One way it is download from http://git-scm.com/download/mac, other options is use MacPorts (www.macports.org) and install executing:

sudo port install git-core +svn +doc +bash_completion +gitweb

Create GitHub account

Create free account in https://github.com/signup/free.

After install Git, the user must generate an SSH key. This is the key used for accessing your GitHub repository. Open a terminal window on Linux/OS X or the Git Bash on Windows.

You can find more information on how to generate SSH Key in http://help.github.com/articles/generating-ssh-keys

Install Git Client

Libelium has chosen a SmartGit/Hg like a graphical Git client which runs on all major platforms. Git is a distributed version control system (DVCS). SmartGit/Hg's target audience are users who need to manage a number of related files in a directory structure, to coordinate access to these files in a multi-user environment, and to track changes to them. Typical areas of application include software projects, documentation projects and website projects.

The user can found SmartGit/Hg in www.syntevo.com/smartgithg/index.html.

Windows

The steps for install SmartGit/Hg in Windows are:

1. Download the Smartgithg from www.syntevo.com/smartgithg/download.htlm
2. Unzip the downloaded file.

3. Execute setup-version-jre.exe and follow the installation instructions.

Linux

If there is no JRE present on your system yet, use the package manager of your distribution to install Java, e.g. from OpenJDK, or download from oracle.com.

The steps for install SmartGit/Hg in Linux are:

1. Download the executable from www.syntevo.com/smartgithg/download.htlm
2. Unzip the downloaded file, execute next command:

   $ tar xvf smartgithg-generic-version.tar.gz

3. SmartGit/Hg are inside smartgithg-version folder-

Mac OS 10.5 +

For Mac OS X, version 10.5 or newer, the necessary JRE is already installed on your system or will be downloaded automatically the first time you launch the application.

The steps for install SmartGit/Hg in Linux are:

1. Download the executable from www.syntevo.com/smartgithg/download.htlm​

2. Unzip the downloaded file, execute next command:

   $ tar xvf smartgithg-generic-version.tar.gz

3. SmartGit/Hg are inside smartgithg-version folder-

Configure Git Client to clone repository

All steps to configure git client are equals for all platforms.

Accept the license for SmargGit/Hg

Figure: Step 1 of the installation ‌

Select Non-commercial use only, Waspmote API is open source, with GPLv3 license.

Figure: Step 2 of the installation ‌

Specify the path to your "git" executable.

Figure: Step 3 of the installation ‌

Select use SmartGit/Hg as SSH client.

Figure: Step 4 of the installation ‌

Specify your user name and your mail to store your commits.

Figure: Step 5 of the configuration ‌

Select "My name main hosting provider is GitHub", and complete the fields with name and pass of GitHub user.

Figure: Step 6 of the configuration ‌

Select "Do not use a master password"

Figure: Step 7 of the configuration

Specify the Git or SVN repository to clone. The repository of Waspmote API Unestable project is:

[e-mail]:Libelium/waspmoteapi_unstable.git

To work with this repository the user must be collaborate. Therefore, each user must fill this field with own repository, create after doing fork.

Figure: Step 8 of the configuration ‌

Select authentication private key type and write private key file and passphrase use in generation SSH key.

Figure: Step 9 of the configuration ‌

Specify the local directory for the new repository

Figure: Step 10 of the configuration ‌

Last, specify the name of the project.

Figure: Step 11 of the configuration ‌

Thread "Repository Code for Developers" on Forum

Inside Forum Libelium LINK PENDIENTE (http://www.libelium.com/forum/), exist a new thread named "Repository Code for Developers".

In this threads users can try and answer your questions with the Libelium technical team.

It is also mandatory for a "Pull Request" to be reviewed and accepted. Users must explain in the forum, what modifications want to commit to the Waspmote API Unstable Repository.

How upload your code to the Waspmote API Unstable repository

Create new fork

Create new fork means clone a repository on your own account. Thus each user can make their own changes. All user of GitHub can create their own fork. It is possible to make fork of Waspmote-API repository and Waspmote-API Unstable repository.

In this guide http://help.github.com/articles/fork-a-repo can be found how create new fork for own project.

Libelium recommend that each user create a new fork and work on their own repositories.

Create a new repository can be done from the web. To create new repository press the button "fork"

Figure: Fork button on GitHub

Create new branch

Branch is a separate line of code with its own history. You can create a new branch of an existing one and change the code independently of other branches.

Branch management is an important part to the git workflow. The user can also choose to manage branches directly on www.github.com

More information about how create and delete branches on repository can be found in: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository

Commit to your own GitHub account

Commit is like committing changes. This creates a new revision, which can be retrieved later, for example, if you want to view or retrieve the source code for an older version. Each commit contains the author and committer or who makes the changes, making it possible to identify the source of change. The author and the committer could be different people.

When a user performs commit, this change will apply to your local repository pressing "commit". In order to upload to the user's account in GitHub you must run "commit & push"from the program SmartGit/Hg

Figure: Commit & push

Commit to the Waspmote API Unstable

To add your code to the Waspmote API Unstable repository, must execute "Pull Request" for the changes to be reviewed and accepted.

Figure: Pull Request

Can find detailed information on how to perform a "Pull Request" http://help.github.com/articles/using-pull-requests.

Once the code is submited, the Libelium Dev Team will review it and will back to you with any doubt or question in order to review it properly.

Figure: Pull Request accepted

IMPORTANT: Addition it is also mandatory for a "Pull Request" to be reviewed and accepted. Users must explain in the Libelium Forum, what modifications made to Waspmote API Unstable code.

Code must be commented so that it keeps understandable and clear for all users.