MethodScript

If you wish to contribute code to CommandHelper, first of all, thank you! CommandHelper has grown into a very large project, and the user base is expanding faster than a single person can develop for. While there are many ways to actually write code, this article outlines the only "officially supported" workflow. You'll need knowledge of a few tools, and a good command of Java to get started though, and so many concepts may be beyond the scope of this article. All contributions must be released according to the [https://github.com/EngineHub/CommandHelper/blob/master/LICENSE.txt MIT submission license], including the [https://github.com/EngineHub/CommandHelper/blob/master/SPECIAL_LICENSE.txt special license] for core code, and is expected to conform to the [https://github.com/EngineHub/CommandHelper/blob/master/CONTRIBUTING.txt code standards]. All code must be submitted as a pull request via github to be considered. Due to the shear size of CommandHelper, it may not be a good starting point for someone that is wishing to get into open source development. However, with dedication, patience, and some critical thinking, you'll definitely be able to contribute. The code in CommandHelper is fairly well organized, follows good [http://en.wikipedia.org/wiki/Software_design_pattern software engineering design patterns], is unit tested, abstracted, and is generally geared towards long term stability and maintainability. Generally speaking, it is not important to fully understand the entirety of the code base before working on it, but you'll need to understand the [[Architecture|Basic Architecture]] before you'll be able to understand where to even begin. The purpose of this article is not to help you understand how to add code to the project, but instead is meant to help you get set up and building the code locally. == Tools == For the most part, the only tool you need is NetBeans. You can download NetBeans [https://netbeans.org/downloads/ here]. The Java SE version is sufficient for CommandHelper, so download that version. NetBeans comes integrated with all the tools we normally need to do things with CommandHelper, but you may want to look at the Advanced Tools section below if you have to do more advanced things from the command line. === Advanced Tools === CommandHelper uses [http://git-scm.com/downloads git] and [http://maven.apache.org/download.cgi maven] for source control and build system, respectively. If you need to do more advanced things with the project, you'll need to download these tools separately and use them from the command line. Follow the directions to download and install them. If you can run git --version and mvn --version from the command line, you have successfully set them up. It is assumed that you know the basics of [http://git-scm.com/documentation git] and [http://maven.apache.org/guides/getting-started/ maven], and so topics like commiting and pulling won't be addressed. ==== Rebasing ==== When submitting a PR, you may have to rebase. If you have several commits, and they are all logically a part of the same code change, and they haven't yet been reviewed, you'll want to ''rebase'' your commits. [http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html This article] goes in depth about how to squash your commits, but the gist is this: If you have 4 commits that you need to rebase, then you would run git rebase -i HEAD~4 to combine the previous 4 commits. If the commit has been reviewed, do NOT rebase at that point, because then the reviewer will have to look at the entire diff again, instead of just looking at the diff from the last time they reviewed the changes. Additionally, if you have several logically separate code changes, it is ok to have them remain separate commits, and is in fact encouraged, so they can selectively be reverted if need be. == Cloning the project == If you intend on submitting code changes, you'll need a fork of the project. You can create a fork on github, and then clone from there. Don't worry, if you clone directly from the main repo (which you won't have commit access to) you can easily create a fork later, and point the remote to there instead. The main repo is read only, so if you only want to build and make changes locally, it is ok to just use the main repo's access url. The access url can be found on the project's github page at the top, and looks like [email protected]:user/project.git. This is the address you'll need. If you don't have a public/private key set up with github, or you don't have a github account at all (you'll need one to contribute, though not to simply pull), you'll need the http url instead: https://github.com/user/project.git and will have to enter your password (or leave it blank for anonymous access). This url will vary depending on whether or not you are checking out from the main project, or your own fork. Click next. You'll probably want to start off with the "master" branch, though you can select any other branches you want too. If you don't get a particular branch right now, that's ok, you can get them later. Set the destination directory (probably ~/NetBeansProjects) and project name, then click finish. It will ask if you want to open the project afterwards. Since CommandHelper is a maven project, it will identify it properly without any extra requirements, so go ahead and open it at this time. === Cloning with NetBeans === To clone the project directly in NetBeans, go to the Team -> Git -> Clone... menu. Enter the access url in the Repository URL field. Depending on whether or not you are using HTTP or SSH, you will see a different interface below. Enter your connection details to continue. If you don't have a public/private key set up with github, you'll need to use the HTTP access url, and you'll enter your username and password. === Cloning from the command line === To clone from the command line, create a new directory, cd into it, and run git clone ACCESS_URL . where the access url is the one we found above. After a moment, all the files will be checked out into this folder. Since the project is a maven project, you won't need to do anything extra for NetBeans (or other IDEs) to recognize it properly. == Building the project == Building the project is equally straightforward, since it uses maven. Maven manages downloading all dependencies, which are specified in the pom, automatically. The first time you build the project it will take a very long time, because it must initially download all the dependencies, which for a completely clean install will be a very large number. You must be connected to the internet for the initial build, but the dependencies are all cached on your system, so future builds won't take nearly as long, and won't require a network connection. === Building in NetBeans === To build the project in NetBeans, right click the project, and select "Build". If you have just switched branches, or something else if going wrong with the build, select "Clean and Build" instead. Cleaning the project clears out all compiled files, and recompiles all sources, but is otherwise the same as a normal build. Notice on the top toolbar, there is a dropdown box that says <default config>. Among possible choices, there will be the "provisional-build" option, which is provided to maven by CommandHelper's pom file. This ''build profile'' causes maven to skip tests, which is useful if you are constantly rebuilding during development, or there are failing tests preventing you from actually compiling a binary. You may select that build profile before building, if desired. Note though that you should build in the default config before committing, to make sure that none of the unit tests fail on your code. === Building from command line === Building from the command line is equally simple. Run mvn install to do the equivalent of the "Build" option in NetBeans, or mvn clean install to clean and build. If you need to set the build profile, use the -P option, so mvn -Pprovisional-build clean install for instance. You can also use the other targets, such as package to create a release zip, which can't be done from NetBeans. == Submitting a PR == To submit a PR, you must have created a fork, and set up a remote for your fork. NetBeans 7.3 allows for all of this to be done from directly inside the GUI, but previous versions required the command line to do some of these things. First, you'll want to make sure that your code is up-to-date against the "upstream" repo, that is, the main repository. Finish all your changes, and commit them to your local repo. Then, pull from the upstream repo to ensure the commit can be cleanly merged (fix any conflict should they arise) and then push to your fork. Once you have pushed, go to your fork in github and click Pull Request. Enter a description of the PR, and submit. Once submitted, you can continue to update this branch, and the new commits will be reflected in the existing PR, however, adding more commits may slow the time it takes to process your PR, so it is a good idea to create a branch and work on that if you need to continue working while the PR is being reviewed. === Pulling from upstream in NetBeans === In NetBeans 7.3, you can right click the project and select Git -> Remote -> Pull from upsream... to pull from another remote. === Pulling from upstream on command line === First, you must add the upstream repo as a remote. To add a remote, run git remote add NAME ACCESS_URL The name can be whatever you like (maybe "upstream" is a good choice) and the access url is the url of the repo you forked from. From that point on, you can run git pull upstream master to pull from the master branch of the upstream repository. You will not be able to push to CommandHelper's main repository, but in general to do so you would run git push upstream master. {{LearningTrail}}

Find a bug in this page? Edit this page yourself, then submit a pull request.