Skip to content

Commit

Permalink
Merge pull request #19 from opencobra/develop
Browse files Browse the repository at this point in the history 
Regular merge of develop
  • Loading branch information
@laurentheirendt
laurentheirendt authored Jun 15, 2018
2 parents b767079 + cea7991 commit 19990fe
Show file tree
Hide file tree
Showing 21 changed files with 175 additions and 670 deletions.
3 changes: 3 additions & 0 deletions .gitmodules
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
[submodule "external/rdir"]
path = external/rdir
url = https://github.com/uni-lu/rdir.git
8 changes: 4 additions & 4 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
67 changes: 44 additions & 23 deletions contribute.m
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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]);
Expand All @@ -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;
Expand All @@ -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
Expand Down
21 changes: 21 additions & 0 deletions docs/source/bestpractices.rst
View file
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions docs/source/contents.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ MATLAB.devTools
installation
getstarted
contribute
bestpractices
modules/index
faq
troubleshooting
Expand Down
9 changes: 4 additions & 5 deletions docs/source/contr_cobratoolbox.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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`).
Expand Down
16 changes: 1 addition & 15 deletions docs/source/faq.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand All @@ -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)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -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
Expand Down
32 changes: 16 additions & 16 deletions docs/source/troubleshooting/cobratoolbox.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
1 change: 1 addition & 0 deletions external/rdir
Submodule rdir added at 0bfa4a
Loading

0 comments on commit 19990fe

Please sign in to comment.