Adding new modules via Git

Wiki > Project tools > Working with git and github > Adding new modules

There are two use cases for adding a submodule:

1. When the code is new, e.g. for a support module for a new device (Marked with New below)
2. When importing code from a 3rd Party e.g. a fork of another github project (Marked with 3rd party below)

1 Create submodule in GitHub

1. Create a new GitHub repository using the "new repository" button on https://github.com/ISISComputingGroup. Name it and fill in a description. The naming conventions are:

   • EPICS submodules should have an "EPICS-" prefix, e.g. for support modules.

2. Decide on public or private repository, if you create it private one you can easily make it public later, but there is a limit on how many private repositories we can have at any one time. Repositories should be private if we do not wish to share the code.

3. Start choice:

   • 3rd Party Create a blank repository i.e. without a README, licence or .gitignore file.

   • New Create a repository with a readme, but no .gitignore or licence. When it is created Use ISIS .gitignore files.

4. Click Create Repository

5. Add team access

   • Select Settings tab
   • Manage Access (left)
   • Click "Invite teams or people" and add ICP-Write group with write access to the repository
   • If it is a private repository add ICP-Read as read only access.

2 Get the repository

1. Move to a new branch in the EPICS directory for your ticket.
2. Create a directory root for the submodule, e.g. for danfysik in support

    cd EPICS/support
    mkdir danfysikMps8000

1. Add a Makefile in the directory, copy it from e.g. ../calc/Makefile
2. Adjust the Makefile in the parent directory to include the new module, e.g. add to SUPPDIRS in ...EPICS\support\Makefile.
3. Add all changes to git.

3a 3rdParty Initial import

Software imported from outside should use a "vendor branch" so new versions are easy to merge in.

1. Create new git repository called master:

    cd EPICS/support/danfysik8000
    mkdir master
    cd master
    git init

1. Unpack the initial vendor code. Often unpacking the code on Linux is preferred as there are less line endings issues.
2. If it unpacks to something like 1-11/... then move everything up a level. You want the top level directory to contain the usual EPICS configure and *App directory layout.
3. Delete any files that are not source files or directories e.g. O.Common, O.linux-x86 , top level bin and lib, db that might have got left in.
4. Delete any .svn directories and files that end in a ~ (temporary files). Then add the files and push to GitHub

   git add .
   git commit -m "Imported danfysik 8000 version 1.11"
   git remote add origin https://github.com/ISISComputingGroup/EPICS-danfysik8000.git
   git push -u origin master

1. Create the vendor branch

    git checkout -b vendor
    git tag -a vendor_1_11 -m "Tag of danfysik 8000 import version 1.11"
    git push origin vendor
    git push --tags

1. Switch to the branch for your ticket (When you create the pull request it can be created from this branch to master):

    git checkout TicketXXX_description

1. Make local changes.

   • Create a readme.md to say where we got the code originally from
   • Add an initial .gitattributes and .gitignore (often using a copy from an older repo).

2. Make sure it builds. You'll probably need to update configure/RELEASE to be like e.g. ../calc/master/configure/RELEASE. Also check the Makefile for both *App and *app targets as well as iocBoot and iocboot - on windows this results in a double match due to case insensitivity, so remove the the *app and iocboot

3b New Initial import

1. Clone the repository in to the correct directory with the directory name master:

    cd EPICS/support/danfysik8000
    git clone https://github.com/ISISComputingGroup/<repo name>.git master

1. Switch to the branch for your ticket (When you create the pull request it can be created from this branch to master):

    git checkout TicketXXX_description

1. Edit/Create a readme.md to say what the module does
2. Add an initial .gitattributes and .gitignore (often using a copy from an older repo).

4 Adding module as submodule

1. Add the new repository as a submodule:

   cd EPICS/support/danfysik8000
   git submodule add https://github.com/ISISComputingGroup/EPICS-danfysikMps8000.git master
   

   note: if the default branch is not master e.g. main is now the default on github then you must specify this with -b e.g.

    git submodule add -b main https://github.com/ISISComputingGroup/EPICS-danfysikMps8000.git master
   

   The master at the end of the command is the local directory name, which we are keeping the same at the moment
2. Add the files generated by adding the submodule

   cd EPICS
   git add .gitmodules
   git commit -m "Add danfysikMps8000 submodule"
   

3. Next make sure that the whole thing builds from the support level (this will only work for a vendor branch).

   cd ..\EPICS\support
   make danfysikMps8000
   git status
   

4. Adjust .gitignore and .gitattributes to make sure they don't contain file that you have just built. Check make clean uninstall works.

Once all the changes are done then create a pull request in the usual way for the new code in EPICS and the new module.

Updating vendor branch

First checkout the vendor branch and remove all files

    git checkout vendor
    rm -fr *

Then unpack the new code into the directory in the same was as above. You'll have files added, removed and changed to handle. Type git status and remove unwanted files like like binaries and temporary files as described above. Then type

    git add -u .

This will add changed files. Again check with a git status that all is looking right before using

    git add .

to add new and remove deleted files. Then commit and tag the changes

    git commit -m "Imported danfysik 8000 version 1.12"
    git tag -a vendor_1_12 -m "Tag of danfysik 8000 import version 1.12"
    git push origin vendor
    git push --tags

Now you need to go back to your ticket branch and merge in new version of vendor code

    git checkout TicketXXX_
    git pull
    git merge vendor_1_12

And resolve conflicts before committing.