Getting Started

The best way to get going with SUCEM:FEM is to fork the development repository in git. This gives you your own repository to work with, should you want to make changes to the source code. Instructions for doing this can be found in the GitHub help files.

Once you have created a fork of the repository, clone this fork to your local development machine by executing the following on the command line:

git clone git@github.com:USERNAME/sucem-fem.git sucem-fem

with USERNAME your git username. This will create a local repository in the sucem-fem folder that is a clone of the forked copy of the project. This will also contain all the history associated with the project. If you only want the most recent changes, use the --depth 1 command line argument.

The next step is to link this local copy with the main sucem-fem repository. To do this, we add a new local branch by executing the following:

git remote add upstream git@github.com:cemagg/sucem-fem

This gives the original sucem-fem repository the name upstream and future changes can be merged into your local branch by executing

git fetch upstream followed by git merge upstream/master

If you have just cloned the repository after a fork, then the chances are that there will be nothing to merge, but it is a good idea to take note of these steps to apply changes that have been made by other developers at a later stage.

If you make changes to your working copy (in the sucem-fem folder on your local machine), it is necessary to commit and push these changes to your repository on github. A few commands that are useful here are

git status which displays the status of the current folder and subfolders if under git version control. Here one can see, for example, if there are any modified files, or if there are files that are not under version control. Files can be added to version control using the git add command.

Once all the desired files have been added, the changes can be committed to the repository using the git commit command. Note that by default git does not commit modified files, and one must either add them again using the add command, or use the -a option for commit.

Note that each commit can be seen as a checkpoint in the code which allows you as a developer to better manage the process involved in adding new features or getting rid of bugs. In addition, since commits are all local, there is no limitation as to how often you can commit to your local repository. Many people feel that committing early and often is the way to go.

Once you have, for example, fixed a bug or added a new feature, you may want to add these changes to your repository on github. This allows other developers to see the changes and also for these changes to be included in the original sucem-fem repository.

To push these changes to your github repository, the git push command is used. Once the push has completed, you can create a Pull Request in your github account which will notify the administrators of the main sucem-fem repository that you have changes that you would like to include. If these are in order, then they will be merged into the main repository and these changes will be available to all with their next execution of

git fetch upstream
git merge upstream/master

The following image attempts to describe the relationship between the different repositories and the commands discussed graphically.