Development
Contents
- Coding conventions in CrisisCommunicator
- Workflow process
- References
We are interested in any contribution. There are many ways how you can contribute:
If you wrote anything interesting using CrisisCommunicator, please send us a patch with the code (see below for more information).
- If you found a bug (or just want to let us know what you think), tell us on the mailinglist. You can also add a bug report (or a comment) into the issues.
- You can help us write documentation (just send us a patch).
- You can help people on our mailinglist.
- You can help with reviewing patches.
- You can send us patches with bug fixes or new features.
The best way to contribute code or documentation is to send us a patch.
Follow the standard Style Guide for Python Code when writing code for SymPy, as explained at the following URLs:
In particular,
-
Use 4 spaces for indentation levels.
-
Use all lowercase function names with words separated by underscores. For example, you are encouraged to write Python functions using the naming convention
def set_some_value()
instead of the CamelCase convention.
-
Use CamelCase for class names and major functions that create objects, e.g.
class PolynomialRing(object)
Note, however, that some functions do have uppercase letters where it makes sense. For example, for matrices they are LUdecomposition or T (transposition) methods.
Creating of environment is once-only.
To install git in Linux-like systems you can do it via your native package management system:
$ yum install git
or:
$ sudo apt-get install git
In Windows systems, first of all, install Python from:
http://python.org/download/
by downloading the "Python 2.7 Windows installer" (or Python 2.6 or 2.5) and running it. Then do not forget to add Python to the $PATH environment.
On Windows and Mac OS X, the easiest way to get git is to download GitHub's software, which will install git, and also provide a nice GUI (this tutorial will be based on the command line interface). Note, you may need to go into the GitHub preferences and choose the "Install Command Line Tools" option to get git installed into the terminal.
If you do decide to use the GitHub GUI, you should make sure that any "sync does rebase" option is disabled in the settings.
Git tracks who makes each commit by checking the user’s name and email. In addition, we use this info to associate your commits with your GitHub account.
To set these, enter the code below, replacing the name and email with your own (--global is optional).:
$ git config --global user.name "Firstname Lastname" $ git config --global user.email "your_email@youremail.com"
The name should be your actual name, not your GitHub username.
These global options (i.e. applying to all repositories) are placed in ~/.gitconfig. You can edit this file to add setup colors and some handy shortcuts:
[user]
name = Firstname Lastname
email = your_email@youremail.com
[color]
diff = auto
status= auto
branch= auto
interactive = true
[alias]
ci = commit
di = diff --color-words
st = status
co = checkout
log1 = log --pretty=oneline --abbrev-commit
logs = log --stat
It can be convenient in future to tune the bash prompt to display the current git branch.
The easiest way to do it, is to add the snippet below to your .bashrc or .bash_profile:
PS1="[\u@\h \W\$(git branch 2> /dev/null | grep -e '\* ' | sed 's/^..\(.*\)/{\1}/')]\$ "
But better is to use git-completion from the git source. This also has the advantage of adding tab completion to just about every git command. It also includes many other useful features, for example, promptings. To use git-completion, first download the git source code (about 27 MiB), then copy the file to your profile directory:
$ git clone git://git.kernel.org/pub/scm/git/git.git $ cp git/contrib/completion/git-completion.bash ~/.git-completion.sh
Read instructions in '~/.git-completion.sh'
Note that if you install git from the package manager in many Linux distros, this file is already installed for you. You can check if it is installed by seeing if tab completion works on git commands (try, e.g., git commi<TAB>, or git log --st<TAB>). You can also check if the PS1 commands work by doing something like:
$ PS1='\W $(__git_ps1 "%s")\$ '
And your command prompt should change to something like:
CrisisCommunicator master$
Note, it is important to define your PS1 using single quotes ('), not double quotes ("), or else bash will not update the branch name.
As you are going to use `GitHub`_ you should have a GitHub account. If you have not one yet then sign up at:
Then create your own fork of the CrisisCommunicator project (if you have not yet). Go to the CrisisCommunicator GitHub repository:
and click the “Fork” button.
Now you have your own repository for the CrisisCommunicator project. If your username in GitHub is mynick then the address of the forked project will look something like:
On your machine browse to where you would like to store CrisisCommunicator, and clone (download) the latest code from CrisisCommunicator's original repository (about 4 MiB):
$ git clone git@github.com:WiseEarthTechnology/CrisisCommunicator.git $ cd CrisisCommunicator
Then assign your read-and-write repo to a remote called "github":
$ git remote add github git@github.com:mynick/CrisisCommunicator.git
Typically, you will create a new branch to begin work on a new issue. Also pull request related with them.
A branch name should briefly describe the topic of the patch or pull request. If you know the issue number, then the branch name could be, for example, 1234_sequences. To create and checkout (that is, make it the working branch) a new branch
$ git branch 1234_sequences $ git checkout 1234_sequences
or in one command using
$ git checkout -b 1234_sequences
To view all branches, with your current branch highlighted, type:
$ git branch
And remember, never type the following commands in master: git merge, git commit, git rebase.
...
...
...
Do not forget that all new functionality should be tested, and all new methods, functions, and classes should have doctests showing how to use them.
You can check what files are changed:
$ git status
Add new files to the index if necessary:
$ git add new_file.py
Check total changes:
$ git diff
You are ready to commit changes locally. A commit also contains a commit message which describes it. See the next section for guidelines on writing good commit messages. Type:
$ git commit
An editor window will appear automatically in this case. In Linux, this is vim by default. You can change what editor pops up by changing the $EDITOR shell variable.
Also with the help of option -a you can tell the command commit to automatically stage files that have been modified and deleted, but new files you have not told git about will not be affected, e.g.,:
$ git commit -a
If you want to stage only part of your changes, you can use the interactive commit feature. Just type:
$ git commit --interactive
and choose the changes you want in the resulting interface.
There are only two formatting rules for commit messages
- All lines should be 78 characters of less. This is so they can be easily read in terminals, which don't automatically line wrap things.
- There should be a single line with a summary, then an empty line, followed
by (optional) additional details. A common convention is to not end the
first line with a
., but all additional lines should (this convention probably exists to save an extra character to make it easier to fit the first line summary in 78 characters).
Some things to note about this commit message:
- The first line gives a brief description of what the commit does. Tools like
git shortlogor even GitHub only show the first line of the commit by default, so it is important to convey the most important aspects of the commit in the first line. - The first line has
integrals:, which gives context to the commit. A commit won't always be seen in the context of your branch, so it is often helpful to give each commit some context. This is not required, though, as it is not hard to look at the commit metadata to see what files were modified or at the commit history to see the nearby related commits. - After the first line, there is a paragraph describing the commit in more detail. This is important, as it describes what the commit does, which might be hard to figure out just from looking at the diff. It also gives information that might not be in the diff at all, such as known issues. Such paragraphs should be written in plain English. Commit messages are intended for human readers, both for people who will be reviewing your code right now, and for people who might come across your commit in the future while researching some change in the code. Sometimes, bulleted lists are a good format to convey the changes of a commit.
- Last, there is an example. It is nice to give a concrete example in commits that add new features. This particular example is about improving the speed of something, so the example is a benchmark result.
Other things to do in commit messages:
- If the bug fixes an issue, reference that issue in the message. Also reference any pull requests or mailing list messages with links. This will make it easier to find related discussions about the commit in the future. You do not need to add a reference to the pull request that contains the commit. That can be found from the git log.
Try to avoid short commit messages, like "Fix", and commit messages that give no context, like "Found the bug". When in doubt, a longer commit message is probably better than a short one.
Be sure that you are in your own branch, and run:
$ git push github 1234_sequences
This will send your local changes to your fork of the CrisisCommunicator repository. Then navigate to your repository with the changes you want someone else to pull:
https://github.com/mynick/CrisisCommunicator
Select branch, and press the Pull Request button.
After pressing the Pull Request button, you are presented with a preview page where you can enter a title and optional description, see exactly what commits will be included when the pull request is sent, and also see who the pull request will be sent to:
If you’re sending from a topic branch, the title is pre-filled based on the name of the branch. Markdown is supported in the description, so you can embed images or use preformatted text blocks.
You can switch to the Commits tab to ensure that the correct set of changes is being sent. And review the diff of all changes by switching to the Files Changed.
Once you’ve entered the title and description, made any necessary customizations to the commit range, and reviewed the commits and file changes to be sent, press the Send pull request button.
The pull request is sent immediately. You’re taken to the main pull request discussion and review page. Additionally, all repository collaborators and followers will see an event in their dashboard.
That's all.
See also Updating your pull request
If after a time you need to make changes in pull request then the best way is to add a new commit in you local repository and simply repeat push command:
$ git commit $ git push github 1234_sequences
Note that if you do any rebasing or in any way edit your commit history, you will have to add the -f (force) option to the push command for it to work:
$ git push -f github
You don't need to do this if you merge, which is the recommended way.
First merge your local repository with the remote:
$ git checkout master $ git pull
This results in:
A---B---C---D master
\
a---b 1234_sequences
Then merge your 1234_sequences branch from 1234_sequences:
$ git checkout 1234_sequences $ git merge master
If the last command tells you that conflicts must be solved for a few indicated files.
If that's the case then the marks >>> and <<< will appear at those files. Fix the code with >>> and <<< around it to what it should be. You must manually remove useless pieces, and leave only new changes from your branch.
commit changes:
$ git commit
So the result will be like that (automatic merging c):
A---B---C-------D master
\ \
a---b---M 1234_sequences
Note: merging is recommended over rebasing.
The final aim, that we want to obtain is:
A---B---C---D master
\
a---b 1234_sequences
The way to do it is first of all to merge local repository with the remote CrisisCommunicator/CrisisCommunicator:
$ git checkout master $ git pull
So we obtain:
A---B---C---D master
\
a---b 1234_sequences
Then:
$ git checkout 1234_sequences $ git rebase master
Note that this last one will require you to fix some merge conflicts if there are changes
to the same file in master and 1234_sequences. Open the file that it tells you is wrong,
fix the code with >>> and <<< around it to what it should be.
Then do:
$ git add blob $ git rebase --continue
(git rebase will also guide you in this).
This page is based upon present CrisisCommunicator pages and inspired by Sage guide [1]:
| [1] | http://sagemath.org/doc/developer/ |