Merge pull request #19 from opencobra/develop

Regular merge of develop

Author: laurentheirendt

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "external/rdir"]
+	path = external/rdir
+	url = https://github.com/uni-lu/rdir.git

README.rst

@@ -97,10 +97,10 @@ You will then be presented by a menu:
 
 ::
 
-       [1] Start a new feature (branch).
-       [2] Select an existing feature (branch) to work on.
-       [3] Publish a feature (branch).
-       [4] Delete a feature (branch).
+       [1] Start a new branch.
+       [2] Select an existing branch to work on.
+       [3] Publish a branch.
+       [4] Delete a branch.
        [5] Update the fork.
 
     -> Please select what you want to do (enter the number):

contribute.m

@@ -1,17 +1,20 @@
-function contribute(repoName, printLevel)
+function contribute(repoName, printLevel, autoOption)
 % devTools
 %
 % PURPOSE: displays a menu and calls the respective subfunctions
 %
-%       1. Start a new feature (branch):
-%       2. Select an existing feature (branch) to work on.
-%       3. Publish a feature (branch).
-%       4. Delete a feature (branch).
+%       1. Start a new branch:
+%       2. Select an existing branch to work on.
+%       3. Publish a branch.
+%       4. Delete a branch.
+%       5. Update the fork
 %
 % INPUT:
 %
+%     repoName:       Name of the repository (default: opencobra/cobratoolbox)
 %     printLevel:     0: minimal printout (default)
 %                     1: detailed printout (debug mode)
+%     autoOption:     menu option
 
     global gitConf
     global gitCmd
@@ -26,14 +29,24 @@ function contribute(repoName, printLevel)
     % adding the src folder of the devTools
     addpath(genpath(fileparts(which(mfilename))));
 
+    % check the automatic option argument
+    autoOptionFlag = false;
+    if exist('autoOption', 'var')
+        if ~isempty(autoOption) && autoOption > 0 && autoOption < 6
+            autoOptionFlag = true;
+        else
+            error('Please enter an automatic menu option between 1 and 5.')
+        end
+    end
+
     % treatment of input arguments
-    if ~exist('repoName', 'var')
+    if ~exist('repoName', 'var') || isempty(repoName)
         DEFAULTREPONAME = 'opencobra/cobratoolbox';  % set the default repository
         repoName = DEFAULTREPONAME;
     end
 
     % soft reset if the repository name is different
-    if ~isempty(gitConf)
+    if ~isempty(gitConf) && exist('repoName', 'var') && isfield(gitConf, 'remoteUserName') && isfield(gitConf, 'remoteRepoName')
         if ~strcmpi(repoName, [gitConf.remoteUserName '/' gitConf.remoteRepoName])
             resetDevTools();
         end
@@ -46,8 +59,10 @@ function contribute(repoName, printLevel)
         checkSystem(mfilename, repoName);
     end
 
+    % perform a soft reset if interrupted
     finishup = onCleanup(@() resetDevTools());
 
+    % determine the directory of the devTools
     devToolsDir = fileparts(which(mfilename));
 
     % change to the directory of the devTools
@@ -56,31 +71,37 @@ function contribute(repoName, printLevel)
     % update the devTools
     updateDevTools();
 
+    % print the launcher
     fprintf(gitConf.launcher);
 
-    choice = input('\n      (You can abort any process using CTRL+C)\n\n      [1] Start a new feature (branch).\n      [2] Select an existing feature (branch) to work on.\n      [3] Publish a feature (branch).\n      [4] Delete a feature (branch).\n      [5] Update the fork.\n\n   -> Please select what you want to do (enter the number): ', 's');
-
-    choice = str2num(choice);
+    % show the menu to select an option
+    if autoOptionFlag
+        choice = autoOption;
+    else
+        choice = input('\n      (You can abort any process using CTRL+C)\n\n      [1] Start a new branch.\n      [2] Select an existing branch to work on.\n      [3] Publish a branch.\n      [4] Delete a branch.\n      [5] Update the fork.\n\n   -> Please select what you want to do (enter the number): ', 's');
+        choice = str2num(choice);
+    end
 
+    % evaluate the option
     if length(choice) == 0 || choice > 5 || choice < 0
         error('Please enter a number between 1 and 5.')
     else
         if ~isempty(choice) && length(choice) > 0
-            % ask for a name of the feature/branch
+            % ask for a name of the branch
             if choice == 1
 
-                % list the available features if the fork is already configured
+                % list the available branches if the fork is already configured
                 if exist('gitConf.fullForkDir', 'var')
-                    %list all available features
-                    listFeatures();
+                    %list all available branches
+                    listBranches();
                 end
 
                 % define a name of an example branch
                 exampleBranch = gitConf.exampleBranch;
 
                 reply = '';
                 while isempty(reply)
-                    reply = input(['   -> Please enter a name of the new feature (branch) that you want to work on (example: ', exampleBranch, '): '], 's');
+                    reply = input(['   -> Please enter a name of the new branch that you want to work on (example: ', exampleBranch, '): '], 's');
                     if ~isempty(strfind(reply, 'develop')) || ~isempty(strfind(reply, 'master'))
                         reply = '';
                         fprintf([gitCmd.lead, 'Please use a different name that does not contain <develop> or <master>.', gitCmd.fail, gitCmd.trail]);
@@ -94,8 +115,8 @@ function contribute(repoName, printLevel)
                 % change to the fork diretory
                 cd(gitConf.fullForkDir);
 
-                %list all available features
-                [exitFlag, currentBranch, ~, exampleBranch] = listFeatures();
+                %list all available branches
+                [exitFlag, currentBranch, ~, exampleBranch] = listBranches();
 
                 if ~strcmpi('develop', currentBranch) && ~strcmpi('master', currentBranch)
                     exampleBranch = currentBranch;
@@ -105,22 +126,22 @@ function contribute(repoName, printLevel)
                     reply = '';
                     if choice == 2
                         while isempty(reply) && ~exitFlag
-                            reply = input(['   -> Please enter the name of the existing feature (branch) that you want to work on (example: ', exampleBranch, '): '], 's');
+                            reply = input(['   -> Please enter the name of the existing branch that you want to work on (example: ', exampleBranch, '): '], 's');
                         end
                     elseif choice == 3
                         while isempty(reply)
-                            reply = input(['   -> Please enter the name of the feature (branch) that you want to publish (example: ', exampleBranch, '): '], 's');
+                            reply = input(['   -> Please enter the name of the branch that you want to publish (example: ', exampleBranch, '): '], 's');
                         end
                     elseif choice == 4
 
-                        % list the available features if the fork is already configured
+                        % list the available branches if the fork is already configured
                         if exist('gitConf.fullForkDir', 'var')
-                            %list all available features
-                            listFeatures();
+                            %list all available branches
+                            listBranches();
                         end
 
                         while isempty(reply)
-                            reply = input(['   -> Please enter the name of the feature (branch) that you want to delete (example: ', exampleBranch, '): '], 's');
+                            reply = input(['   -> Please enter the name of the branch that you want to delete (example: ', exampleBranch, '): '], 's');
                         end
                     end
                 end

docs/source/bestpractices.rst

@@ -0,0 +1,21 @@
+.. _bestpractices:
+
+Best practices
+==============
+
+Naming a contribution
+---------------------
+
+Initiate a contribution per theme/topic/feature/bug fix that you work
+on. Don’t mix features and think of an explicit name, i.e.
+``bug-fix-function1`` or ``add-tests-function2``. Avoid generic names,
+such as ``my-great-feature`` or ``fix`` or ``contribution-myName``.
+
+Submitting a Pull Request (PR)
+------------------------------
+
+Once you submit your contribution (menu option [3]), you will be
+presented with a link that leads you directly to the pull request (PR).
+Once the PR is submitted, wait until it is reviewed and accepted.
+Once merged, please start a new branch by running ``contribute`` and
+selecting [1] after your pull request has been reviewed and merged.

docs/source/contents.rst

@@ -8,6 +8,7 @@ MATLAB.devTools
    installation
    getstarted
    contribute
+   bestpractices
    modules/index
    faq
    troubleshooting

docs/source/contr_cobratoolbox.rst

@@ -12,7 +12,7 @@ Introduction
 
 A comprehensive code base such as the COBRA Toolbox evolves constantly. The
 open-source community is very active, and collaborators submit their
-contributions frequently. The more a new feature or bug fix is interlinked with
+contributions frequently. The more a change to code or bug fix is interlinked with
 existing functions, the higher the risk of a new addition breaking instantly
 code that is heavily used on a daily basis. In order to decrease this risk, a
 continuous integration setup interlinked with the version control system git
@@ -22,8 +22,7 @@ other documents of which all incremental changes are tracked by date and user.
 Any incremental changes to the code are called commits. The main advantage of
 git over other version control systems is the availability of branches. In
 simple terms, a branch contains a sequence of incremental changes to the code.
-A branch is also commonly referred to as a feature. Consequently, a
-contribution generally consists of several commits on a branch.
+Consequently, a contribution generally consists of several commits on a branch.
 
 Contributing to the COBRA Toolbox is straightforward. As a contributor to the
 COBRA Toolbox is likely more familiar with MATLAB than with the internal
@@ -170,12 +169,12 @@ Deleting a contribution
 -----------------------
 
 If a contribution has been merged into the develop branch of the opencobra
-repository (accepted pull request), the contribution (feature or branch) can be
+repository (accepted pull request), the contribution (branch) can be
 safely deleted both locally and remotely on the fork by running contribute and
 selecting procedure ``[4]``.
 
 Note that deleting a contribution deletes all the changes that have been made
-on that feature (branch). It is not possible to selectively delete a commit
+on that branch. It is not possible to selectively delete a commit
 using the MATLAB.devTools. Instead, create a new branch by following procedure
 ``[1]``, and follow the instructions to cherry-pick (see
 :ref:`troubleshooting`).

docs/source/faq.rst

@@ -6,14 +6,6 @@ Frequently Asked Questions (FAQ)
 General questions
 -----------------
 
-How should I name my contribution?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Initiate a contribution per theme/topic/feature/bug fix that you work
-on. Don’t mix features and think of an explicit name, i.e.
-``bug-fix-function1`` or ``add-tests-function2``. Avoid generic names,
-such as ``my-great-feature`` or ``fix`` or ``contribution-myName``.
-
 How can I check the history of a file?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -23,12 +15,6 @@ You can check the history of a file by typing in MATLAB:
 
     >> history('fileName.m')
 
-How do I submit a Pull Request (PR)?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Once you submit your contribution (menu option [3]), you will be
-presented with a link that leads you directly to the pull request (PR).
-
 Print more detailed debugging information (verbose)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -62,7 +48,7 @@ You may encounter the following error:
 
 This error can have multiple reasons, but most likely, the SSH key is
 not configured properly. Please follow the `configuration
-instructions <https://github.com/opencobra/MATLAB.devTools/blob/master/PREREQUISITES.md>`__
+instructions <https://opencobra.github.io/MATLAB.devTools/stable/installation.html#pre-requisites>`__
 carefully.
 
 Another source of this error may be that you have set a passphrase when

docs/source/troubleshooting/cobratoolbox.rst

@@ -23,10 +23,10 @@ COBRA Toolbox are consequently commits that are made on branches.
 
 The development scheme adopted in the repository of the COBRA Toolbox has two
 branches: a `master` and a `develop` branch. The stable branch is the `master`
-branch, while it is the `develop` branch that includes all new features and to
+branch, while it is the `develop` branch that includes all new changes to code and to
 which new contributions are merged. Contributions are submitted for review and
 testing through pull requests, the `git` standard. The `develop` branch is
-regularly merged into the `master` branch once testing is concluded. 
+regularly merged into the `master` branch once testing is concluded.
 
 The development scheme has been adopted for obvious reasons: the COBRA Toolbox
 is heavily used on a daily basis, while the development community is active.
@@ -55,7 +55,7 @@ This will create a folder called fork-cobratoolbox. Make sure to replace
 to be run from within the folder of the fork called `fork-cobratoolbox`.
 
 .. code:: console
-    
+
     $ cd fork-cobratoolbox
 
 In order to complete the cloned repository with external code, it is
@@ -125,7 +125,7 @@ contribution. A new contribution must be made on a new branch, that originates
 from the `develop` branch. Create the new branch:
 
 .. code:: console
- 
+
     $ git checkout -b <myBranch> develop
 
 Now, you can make changes in the folder `fork-cobratoolbox`. Once you are done
@@ -145,29 +145,29 @@ adding the file:
 
 |warning| Contrary to what is sometimes provided as a shortcut, it is not
 advised to add all files all at once using as this command will add all files,
-even hidden files and binaries. 
+even hidden files and binaries.
 
 .. code:: console
 
-    $ git add . # bad practice 
+    $ git add . # bad practice
 
-Then, commit the changes by setting a commit message <yourMessage>: 
+Then, commit the changes by setting a commit message <yourMessage>:
 
 .. code:: console
 
     $ git commit -m "<myMessage>"
 
-Finally, push your commit to Github: 
+Finally, push your commit to Github:
 
 .. code:: console
 
-    $ git push origin <myBranch> 
+    $ git push origin <myBranch>
 
 You should then see your commit online, and if ready, you can open a
 pull request. You can select your branch in the dropdown menu and list all
 commits by clicking on `commits`.
 
-Continue working on your branch after a while (rebase) 
+Continue working on your branch after a while (rebase)
 ------------------------------------------------------
 
 If there have been major changes or if you want to continue working on a branch
@@ -177,7 +177,7 @@ from the upstream repository. Before doing so, make sure that you do not have
 any uncommitted or local changes (git status).
 
 .. code:: console
- 
+
     $ git checkout develop
     $ git fetch upstream
     $ git merge upstream/develop
@@ -191,26 +191,26 @@ use a merge tool such as `kdiff3`. In order to install a merge tool or abort
 the rebase process, type:
 
 .. code:: console
- 
+
     $ git rebase --abort
 
 In order to have the changes on `<myBranch>` reflected in the online
 repository, push the changes with force. Pushing with force is required as the
 history of the branch has been rewritten during rebase.
 
 .. code:: console
- 
+
     $ git push <myBranch> --force
 
-Selectively use a commit on your branch (cherry-pick) 
+Selectively use a commit on your branch (cherry-pick)
 -----------------------------------------------------
 
 Imagine having two branches called `<myBranch-1>` and `<myBranch-2>`. On branch
 `<myBranch-1>` is a commit with a SHA1 that you need on `<myBranch-2>`. You can
 cherry-pick the commit from `<myBranch-1>` to `<myBranch-2>` by typing:
 
 .. code:: console
- 
+
     $ git checkout myBranch-2
     $ git cherry-pick SHA1
 
@@ -219,6 +219,6 @@ message and author information. In order to have the commit listed online,
 conclude the cherry-pick by pushing the commit to the remote repository:
 
 .. code:: console
- 
+
     $ git push myBranch-2