Dev: Guidelines

Repositories

Source code repositories of existing projects are imported into LuaDist as follows:

• Projects already in git(hub) are forked. https://github.com/LuaDist/vstruct/network
• For lhf projects, we just import the latest 4.0, 5.0, and 5.1 tarballs. https://github.com/LuaDist/lpack/network
• For luaforge projects, recently partially converged to git, we cleanup the git conversion. https://github.com/LuaDist/luazip/network
• For google code projects without a lot of svn history, just use git-svn. https://github.com/LuaDist/luaex/network
• Other cases may still be decided. See Dev:-notes for details on how each import is done.

All LuaDist repositories should follow these simple rules.

• Tags should always follow the version in dist.info.
  • If tag already exists for add an incremental "-1" "-2" .. "-n" suffix to the version tag.
  • No "v" prefix. (DM: why?)
  • Do not tag development versions.
  • Original repository tags need to be removed. (Fetch changes with --prune --tags)
    • NOTE: This is still under discussion. Keeping original tags can break automation.
• Master branch should always point to most recent package version.
• All new modifications should be developed in branches other than master.
  • Recommended branch names are "packagename-version" or "feature name"

LuaDist/Repository

Primary repository that aggregates all module sub-repositories in the distribution. The purpose of this repository is to ease development and generate dist.manifest file for the deployment utility. While working with this repository keep the following in mind:

• ! All Development issues go here.
  • Issues in other repositories are discouraged.
• Submodules DO NOT point to master.
  • When working with a repository always check your branch, you may loose your changes.
  • Make sure the repository is up to date.
• If you update master branch of any module make sure LuaDist/Repository points to it.

Workflow

The following section will describe recommended workflow for LuaDist development. This includes setup of the environment. Utilization of the Repository and some connivence settings for the LuaDist utility.

Step 1. Checkout and work in LuaDist/Repository only.

$ # Checkout the work repository 
$ git clone git://github.com/LuaDist/Repository.git
$ cd Repository

Step 2. Bootstrap LuaDist

$ # You can check out any submodule you want to work on in the same manner
$ git submodule update --init lua luafilesystem luadist md5 luasocket luasec openssl unzip
$ ./install bootstrap
$ mv _install LuaDist

Step 3. Configure LuaDist to use local Repository as primary dist source

$ # Edit LuaDist config
$ nano LuaDist/lib/lua/dist/config.lua

Add path to the local repository as follows:

-- URLs of repositories to search for dists. http:// or file:// URLs are cecognized atm.
repo = {
	--- Use local repo to speed things
	"file:///home/myself/luadist/Repository/",
	--- Official repo
	"https://github.com/LuaDist/Repository/raw/master/"
}

Now your local repository has precedence when installing modules. Modules not available in it will be fetched online.

Step 4. New modules

To add a new module first create the repository on github and then add a submodule to Repository as follows:

$ # NOTE: Add READ ONLY URLs so this repository can be checked out by anyone
$ git submodule add git://github.com/LuaDist/module.git
$ cd module

Step 5. Compilation and Development

Once you are done with your work you can install the module using LuaDist into a test folder:

$ LuaDist/bin/luadist _test install module -verbose=true

This will also look for any dependencies the module has. To reinstall it you can call make instead of install, the difference is that it overwrites the install, does not take dependencies into account and expects a path as the module identificator.

$ cd module
$ ../LuaDist/bin/luadist make . -verbose=true
$ # Repeat until development is done

Step 6. Publishing the module

When you are done developing you need to push the work into the module repository and update Repository and its manifest.

$ # Since the repository is readonly we need to change the push path, this will do it for all submodules
$ git submodule foreach 'git remote set-url --push origin [email protected]:LuaDist/$path.git'
$ cd module
$ # Add your work
$ git add ...
$ # Commit locally
$ git commit -a -m "Commit message"
$ # Add version tag if needed
$ git tag 0.1
$ # publish
$ git push

Step 7. Updating Repository

Once this is done we need to push Repository changes:

$ # Update manifest (get a coffee)
$ LuaDist/bin/lua manifest.lua
$ # Commit and publish
$ git commit -a -m "Added/Updated module"
$ git push

You can delete the local submodule and check install from online

$ rm -rf module
$ LuaDist/bin/luadist _test install module

Hopefully all goes ok. Have fun developing.