View source for Maintain packages with Git

[https://en.wikipedia.org/wiki/Git Git] is a distributed version-control system for tracking changes in source code during software development. It is designed for coordinating work among programmers, but it can be used to track changes in any set of files.

Some, but not all, packages developed for the Humax use Git to maintain the associated source code.  This allows for better tracking and control of changes and, potentially, allows for multiple users to collaborate on maintaining the package by making and testing changes on a private copy of the package and then submitting them for review and incorporation into the main package for distribution to the Humax community via the normal package update mechanism. 

This wiki page attempts to describe the basics required to submit a change to a package that you don't own using the ''webif'' package as an example.  It was written by a naive new user of Git and does not attempt to cover all of Git / Github and may contain errors, please correct and update this page where needed!

Git repository = Storage location for a single humax package

== Initial setup ==
Install, using the normal Humax package install method, the following (may need to show Advanced packages):
* git
* pkgtools
* gzip
* A text editor, Joe, Nano, or Vim unless you are happy with the default Vi

Create a user account on the hummy package git repository site https://git.hpkg.tv/ userid should normally be the same as your forum id,
Optionally also create an id on the the public git repository [https://github.com github]

All commands shown should be issued from a command prompt (telnet, putty, or Command Line on webif Diagnostics page)

Create a directory to hold git repositories (do not use /mod directly to avoid conflicts with installed packages)
<pre>
md /mod/git
cd /mod/git
</pre>
Set up some defaults for Git based on your details and preferences. The credential.helper timeout will remember your password for 24 hours 
<pre>
git config --global user.name "USERNAME"
git config --global user.email "EMAIL"
git config --global core.editor "editor"
git config --global credential.helper 'cache --timeout=86400'
</pre>
== Fork and clone reposiory ==
Sign in and find the package you want to work with on the host repository eg https://git.hpkg.tv/hummypkg/webif 

If the package you are interested in is not visible on the website contact the package owner to discuss access.

Click on the Fork button (top right) and create a forked repository
(using a fork creates a private copy and insulates your changes from those on the master, it is not needed if you are the repository owner)
Copy the the HHTPS url for the forked repository, ensure you are in your git folder on the humax  and paste it into a ''git clone'' command
<pre>
cd /mod/git
git clone https://git.hpkg.tv/USERNAME/webif.git
</pre>
Change to your repository directory and add the master repository as another remote - this enables you to pick up changes made to the master
<pre>
cd /mod/git/webif
git remote add upstream https://git.hpkg.tv/hummypkg/webif.git
</pre>
You now have two remotes for this project on disk:
# origin which points to your fork of the project. You can read and write to this remote.
# upstream which points to the main project’s repository. You can only read from this remote.

== Sync with master ==
You don't need this step if you have just forked and cloned the master, but if time has elapsed and master may have changed you can pull in the latest changes and push them up to your host repository
<pre>
cd /mod/git/webif
git checkout master
git pull upstream master 
git push origin master
</pre>
== Create a Branch ==
Every related set of changes should be in its own branch, don't try and fix unrelated problems in the same branch.
Branch names should be meaningful.
<pre>
cd /mod/git/webif
git checkout -b FixBrowseTypo
git push -u origin FixBrowseTypo
</pre>
The -b flag is only needed for a new branch, not when switching to existing branch

== Make your updates ==
Using your favourite text editor make the necessary changes to the code. 
== Package, Install and test fixes ==
For simple changes you may be able to test the changes in isolation without needing to package and install for each update but to fully test using the webif it is best to properly package and install your changes.
Update CONTROL/control for the package to update the version number,  check the dependencies section if your changes depend on new or updated packages (or remove existing dependencies).  See the "[[Create Packages]]" page for more information on the control file structure.
Create package .opk file and install it (vers#) is the number from the control file
<pre>
cd /mod/git
opkg-pack webif
opkg install webif_vers#_mipsel.opk
</pre>
If the opkg-pack fails with 'Resource temporarily unavailable' messages try again - it seems to resolve itself after a few goes.
Test to ensure your changes are working as intended.
== Commit your changes ==
Committing saves your updates in the local Git repository and allows you to revert to any previous commit point should you need to back out a change,  for a small change you may only need to commit once but for larger changes you can split your work into logical chunks and commit each piece.  Pushing then syncs your remote repository with the changes from your local repository.

Before committing Git needs to know which of the changes you have made in the repository folder are to be included in the commit, this is known as staging and can be done in several ways.

To add a file to the next commit
<pre>
git add file.name
</pre>
To add all changed files to the next commit
<pre>
git add .
</pre>
To see the current status, very useful for checking what will / won't be committed 
<pre>
git status
</pre>
To discard changes to a file
<pre>
git checkout -- file.name
</pre>
To commit all changed files use the -a flag on the commit command (alternative to ''git add .''), if the -m flag is omitted it will open an editor window for you to type a commit message 
<pre>
git commit -a -m "Summary of the changes"
</pre>
=== Omit CONTROL/control from commits ===
When different branches have changes to the same file Git can normally automatically merge the changes provided they don't affect the same lines of the file when you have to resolve the conflicts and decide which version to keep,  not hard but extra work for the package owner.
Changes to the package version number obviously all affect the same line of the control file and will cause conflicts if several changes are to be combined into one update of the Humax package.
So unless you have made other changes (e.g. Dependencies) I suggest that you backout changes to the control file before committing.
<pre>
git checkout -- CONTROL/control
</pre>
== Create a Pull Request ==
A ''Pull Request'' is a request to the package owner to merge your changes into the Master repository and update the Humax package.
The New Pull Request button appears in a number of places on the remote repository pages under the Branches or Pull Requests tabs.

Ensure you specify the master branch of the master repository as the target for merge into and your branch to pull from
[[File:PullRequest.png|frame|centre|Creating a Pull Request]]

The title and description of the Pull Request should explain to the package owner why your changes should be included in the package.
Assign the request to the owner in the assignee tab (on the right of the page)

The owner will review your changes and may request changes which should be made and committed on the same branch (a new Pull request is '''not''' needed)

When happy with the changes the owner will merge the branch into master and close the Pull Request, the branch can be deleted and you can start again at the [[Maintain_packages_with_Git|Sync with master]] step
== Further Information ==
This page only scratches the surface of Git and there are numerous reference works and tutorials on github and elsewhere on the web.  A few links that have helped me are:
* [https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/ The beginners guide to contributing to a github project]
* [http://www.bioinf.org.uk/teaching/bbk/biocomp2/git/git.pdf An introduction to Git and GitHub]
* [https://www.atlassian.com/git/tutorials Git Tutorials]