Contributing Code back to N2

One of the key features of N2CMS is our vibrant community of users and developers. When you extend N2CMS to meet your own, your customers, or your organizations' needs, we encourage you to commit useful portions of what you create back to the community, so that others can benefit from your work. Think of the time that N2CMS saves you! Your contributions will help our thousands of users in turn. 

Why share your code back to the N2 project?

• Give back to the community that gave you this awesome software (and documentation!)
• Community code reviews will find even more bugs
• Further community contributions will improve upon your code, adding value that you can pass back to your customers at no additional cost to you!

We will consider every contribution, and we want to make it as simple as possible. This article should contain everything you need to know about contributing code back to N2. 

Licensing your contributions

You retain ownership of code you contribute to N2CMS. Under U.S. copyright law, an author automatically owns the copyright to anything that author created. However, in some countries, you may need to explicitly declare copyright. A copyright statement should appear at the top of every file you commit. N2CMS itself is licensed under the LGPL license. That means while you can link your own code against the N2CMS libraries and license that linked code any way you want (including not licensing it at all), any derivative works or modifications to the N2CMS library itself are licensed under the LGPL. 

You can license your contribution by adding a comment header to the file you're committing. If you're modifying a file that is already part of N2CMS, you shouldn't add a header because that file is already covered by the N2CMS LGPL license.

Adding files and Committing

Sending a Pull Request

Updating Your Fork from Official Branches

Graphical User Interface (GUI) Alternatives to the Git Command Line

We know the command line isn't a hospitable environment for some users and developers. Luckily, for you folks who prefer a GUI environment to the Git command line, free solutions are available!

Setting up SourceTree

First, you need to fork the repository on Github per the instructions above. 

1. click Clone/New in the toolbar. Under Source Path / URL, enter the URL to your fork of the N2CMS repository (see above). 
2. specify the destination path on your PC where you want to save the source code
3. click Clone and SourceTree will set up your own copy of the repository. 

Now, you need to add a remote for the official n2cms branches, so that you can pull changes from there. 

1. make sure that your n2cms clone is open in SourceTree (double-click the item in the repository list on the left) 
2. right-click Remotes and click New Remote
   
3. In the New Remote dialog, fill in the required properties
   
   1. Remote name: github-n2cms
   2. URL / Path: git@github.com:n2cms/n2cms.git
4. Click OK to save the Remote 
5. You can now fetch and pull (which is equivalent to fetch+merge) changes from the official Github repository into your own local copy. When you've done that, you can push those changes to your Github fork copy as well. 

Visual Studio 2013 and GitHub

To be able to contribute back to N2 project you should first clone N2 repository on GitHub

1. Go to https://github.com/n2cms/n2cms
2. Login to GitHub
3. Press [Fork] button on upper right part of screen
4. Why do I need this?
   1. This is your playground: you may modify source files in your repository in any way you wish.
   2. As soon as you are ready to contribute your work back to N2 you may post your changes in form of "Git Pull Request".

Configure Visual Studio for Git

1. Select menu "Tools/ Options" and select "Source Control"
   1. Select "Microsoft Git Provider"

Use Visual Studio to setup N2 source code on your computer

1. Select menu "View/ Team Explorer" 
2. In "Local Git Repositories" section select "Clone" command
3. Enter:
   1. Url to your GitHub repository
   2. Check / change local path where source code will be stored on your computer
4. Press [Clone] button
5. Visual Studio will do a "clone" from your GitHub repository to your computer,
   that is it will copy N2 source code to your computer.
6. See also: Use Visual Studio with Git -http://msdn.microsoft.com/en-us/library/hh850437.aspx

Visual Studio: committing changes and pushing changes back to your repository

1. Select menu "View/ Team Explorer",  click in title bar to get dropdown, select "Changes"
2. See "Included changes" section for changed files that are under Git control
3. To commit changes enter a short description of that particular commit and select a command
   1. [Commit] will mark changed files as committed (changes won't be sent to server yet, commit may still be revoked)
   2. [Commit and Push] will do a commit and will sent changes to your repository on GitHub
   3. [Commit and Sync] will do "commit and push" and after that will pull all changes from your GitHub repository to your computer
4. Note: you may navigate to GitHub and check your pushed commits there.

GitHub: preparing a "Pull Request" to N2 team

1. Carefully check modified sources pushed to your repository on GitHub
2. Press [Pull Request] button, create New Pull Request, enter description of your changes, re-check your source code changes - and send it. 

Why wasn't my pull request accepted?

Unfortunately, we aren't able to merge every pull request. A member of the N2CMS developer team will let you know in the pull request itself why the pull request isn't accepted. In some cases, we might make modifications to your code as a condition of its acceptance. Or, we might ask you to fix a problem or two and merge it afterwards.