Contributing to Sif 3 Framework .NET

Guidelines for contributing changes

sif-framework-dotnet is part of a structure that includes both global and locale repositories. Generally you will contribute only to the locale repository. [This page](Structure of sif framework repositories) may help you better understand the global/locale repository structure.

For some background information regarding the branching model used by this project, refer to the article A successful Git branching model. The ideas from that article have been combined with the collaborative development techniques recommended by GitHub (specifically Using Pull Requests) to form these procedures.

To reduce unnecessary work for others, please structure your contributions into grouped, tested, working patches before offering them to the administrators. For guidelines about this and other good practices, refer to the article Commit Often, Fix it Later, Publish Once: Git Best Practices.

Pre-requisities

• Git installed.
• A strong understanding of Git. For an introduction, read Getting Started - Git Basics.
• A GitHub account and Pull access to the NSIP repositories.

Defined Repositories

The procedures following refer to 3 Git repositories:

• The remote (upstream) Sif3Framework-dotNet repository containing a central copy of the code.
• Your remote repository created within your GitHub account.
• Your local repository residing on your local machine.

Getting the code

1. Fork the Sif3Framework-dotNet repository into your remote repository (click on the "Fork" button).

2. Clone your fork to create your local repository. This will create a Sif3Framework-dotNet directory on your local machine.

   c:\dev> git clone https://github.com/USERNAME/Sif3Framework-dotNet.git
   

3. Add the upstream (Sif3Framework-dotNet) repository as a remote. This will allow you to keep track of the Sif3Framework-dotNet repository and pull in updates.

   c:\dev> cd Sif3Framework-dotNet
   c:\dev\Sif3Framework-dotNet> git remote add upstream https://github.com/nsip/Sif3Framework-dotNet.git
   

4. In your local repository, set up a tracking branch for the develop branch of your remote repository and switch to it.

   c:\dev\Sif3Framework-dotNet> git checkout -t origin/develop
   

5. If you wish to create a topic branch in your local repository, please ensure that it is based upon the develop branch. Do not base your topic branch on the master branch!

   c:\dev\Sif3Framework-dotNet> git branch ISSUE_XXX develop
   c:\dev\Sif3Framework-dotNet> git checkout ISSUE_XXX
   

Ensuring you remote repository is up-to-date

To sync your remote repository with the upstream (Sif3Framework-dotNet) repository, fetch all upstream changes into your local repository and then push them from your local repository to your remote repository.

1. Fetch all changes from the upstream repository and merge into your local repository.

   c:\dev\Sif3Framework-dotNet> git fetch upstream
   c:\dev\Sif3Framework-dotNet> git checkout develop
   c:\dev\Sif3Framework-dotNet> git merge upstream/develop
   

2. Push the updates in your local repository to your remote repository.

   c:\dev\Sif3Framework-dotNet> git push origin develop
   

Submitting a change

Before submitting a change, ensure that your local repository is up-to-date with the upstream repository (as outlined in the previous section).

1. Commit all local repository changes with an informative message. The -a flag skips staging.

   c:\dev\Sif3Framework-dotNet> git checkout develop
   c:\dev\Sif3Framework-dotNet> git commit -a -m MESSAGE
   

2. Push the updates in your local repository to your remote repository.

   c:\dev\Sif3Framework-dotNet> git push origin develop
   

Issue a Pull Request

The Using Pull Requests article provides a comprehensive guide for issuing a Pull Request.

1. Browse to your remote (forked) repository on the GitHub site.

2. Switch to the appropriate (develop) branch and press the "Pull Request" button.

3. Review the Pull Request details, and provide a meaningful title and description of your change. On the "Comparing changes" page, it is important to ensure that the base branch (base:) is set to develop and the head branch (compare:) is set to your develop branch. Pull Requests will not be accepted against the master branch of the Sif3Framework-dotNet repository.

4. Press the "Send pull request" button.