Contribution

Contributing to Qucs

The Qucs project is undergoing rapid development and any kind of help is welcome.

There are a number of ways you can contribute to the project:

• Writing code: fixing bugs, proposing new features.
• Become a translator: keep the translation on your language updated.
• Helping to resolve existing issues: verifying existing Bug Reports and testing patches.
• Reporting bugs: little bugs always sneak in, we need people to spot them.

To be up to date with the current Qucs development, please subscribe to watch the Qucs repository on GitHub and subscribe to the Qucs mailing lists. For these latter, you have to be a subscriber to send messages (to avoid spam); attachments are limited to 50KB.
Some of the Qucs developers can also sometimes be found on the IRC #qucs channel on freenode.net.

To contribute code changes you must become familiar with Git. Git is a version control system that helps people to keep track of the history of changes on files.
The Qucs project uses both GitHub and Sourceforce as Git repositories of the source code. This Wiki is hosted on GitHub.
If you do not yet have a GitHub account, create one. With an account you can start participating in the Qucs development, fork projects, create issues, comment on existing issues, edit the public Wikis.
New contributors are advised to read the GitHub guide Contributing to a Project and become familiar with the GitHub pull request mechanism used to sending code changes between developers.

Contributing code:

IMPORTANT: By submitting your contribution, you agree to license your code under the GPLv2+ license used by Qucs

Please ask first on the qucs-devel mailing list before embarking on any significant pull request (e.g. implementing new features, refactoring code), otherwise you risk spending a lot of time working on something that the project developers might not want to merge into the project.

If you would like to work on a currently un-assigned GitHub issue, feel free to grab it and ask any clarifying questions needed commenting on that issue. If there is an issue you'd like to work on that's assigned and stagnant, please ping the assignee and finally qucs-devel. before taking over ownership for the issue.

If you are new to GitHub, see below for a detailed typical workflow.

To submit your contribution please send a GitHub Pull Request with a clear list of what you've done. Please thoroughly test your changes before submitting; that means not only checking that your modifications fix the bug or enable the new feature you were targeting but also that no side effects or additional bugs were introduced.
If you made changes to the Qucs simulator (qucsator) in qucs-core make sure that the test suite in qucs-test still runs without errors.
For changes to the GUI there is no automated test suite available; please spend some time checking your change for any side effect.

Workflow

The typical workflow to contribute code changes on GitHub is

1. Get a copy of the source code

• Create a personal fork of Qucs on your GitHub account.
• Clone the Qucs main repository on your computer.

2. Make changes

• Create a local branch and commit your changes.
• Push your local branch to your personal fork.

3. Publish your changes

• Create a pull request from your fork to the Qucs repository.

4. Update your sources

• Update your local clone from the main repository before doing new changes.

All these steps are detailed below; we assume here you are at least a little familiar with the Git philosophy and terminology.

Get a copy of the source code

To start making changes to the code, you will need to have a copy of it on your computer. This can be done by cloning the main Qucs repository directly or by cloning your fork created on GitHub.
In the following, the remote repository of your fork will be called origin, while the main Qucs remote repository will be named upstream, as done in the GitHub documentation on how to fork a repository and the GitHub Glossary page.

If you have already cloned the Qucs repository directly, without creating a fork, see below. Otherwise follow these steps:

• log into your GitHub account and browse to the Qucs repository
• press the Fork button to create your fork.
• now you need to clone your fork on your computer: type
  git clone <your_github_repo_link>
  where <your_github_repo_link> is the HTTPS clone URL on the right of your GitHub page, usually something like https://github.com/<username>/qucs.git

The remote repository corresponding to your Qucs fork is now named origin. To verify, type
git remote -v
and the output should be something similar to

origin  https://github.com/<username>/qucs (fetch)
origin  https://github.com/<username>/qucs (push)

You now need to add the Qucs repository as upstream, by typing
git remote add upstream https://github.com/Qucs/qucs.git

Now
git remote -v
should show something like

origin   https://github.com/<username>/qucs (fetch)
origin   https://github.com/<username>/qucs (push)
upstream   https://github.com/Qucs/qucs (fetch)
upstream   https://github.com/Qucs/qucs (push)

You already cloned the Qucs repository

If you have already cloned the Qucs repository directly, for example using git clone https://github.com/Qucs/qucs.git, you will by default have the origin remote pointing to the Qucs repository. You need to change this to tell Git to use your fork as origin and the original Qucs repository as upstream.
Check by typing
git remote -v
if the output is something like

origin  https://github.com/Qucs/qucs (fetch)
origin  https://github.com/Qucs/qucs (push)

You need to correct it to have the upstream remote pointing to the Qucs repository by typing
git remote rename origin upstream
then you need to have origin pointing to your fork, by typing
git remote add origin <your_github_repo_link>

Now
git remote -v
should show something like

origin   https://github.com/<username>/qucs (fetch)
origin   https://github.com/<username>/qucs (push)
upstream   https://github.com/Qucs/qucs (fetch)
upstream   https://github.com/Qucs/qucs (push)

Make changes

After release 0.0.18 the project started to use the Git flow strategy for branching http://nvie.com/posts/a-successful-git-branching-model/.

Under this strategy the following branches can be found in the repository:

• master: contains the latest stable release.
• develop: contains the latest developments or unstable. This should be the base branch of Pull-Requests or contributions.
• release-x.y.z: are temporary branches being stabilized for a release. To be merged into master and removed.
• [other branches]: are branches with a good reason to be in the main repository (ease collaboration, use CI facilities).

Please keep these branches of your fork 'clean': you should use it only for staying in sync with the upstream repository. See below for the commands to use to sync your local branches with the Qucs repository.
Don't commit to any of the branches above or merge your commits into them. Instead, set up your own branches to work on changes.

To start making changes

• Make sure you are on the right branch to use as a starting point for your modifications. Use
  git checkout [branch name]
  to select one of the branches mentioned above. If unsure about which one to use, ask. Anyway, this can be corrected later in case you used the wrong one.

• Create a new branch for your changes
  git checkout -b <my-feature-branch>
  where <my-feature-branch> is the name of the branch you would like to create. It is arbitrary but try to use a meaningful name.

• Make changes on your local copy
  Edit a file, add or remove files.

• Review the changes. Play with the commands:
  git diff
  and
  git status
  to see which files have been changed

• Prepare to commit, stage your changes.
  To stage your changes you can use
  git add <modified files>
  or also
  git add . to add all modified files
  git add -u . to add only modified files (not the untracked ones)
  git add . to add to index only files created/modified and not those deleted
  git add -u to add to index only files deleted/modified and not those created
  git add -A to do both operation at once, add to index all files

• Commit your changes.
  git commit
  Please see below for general Rules about commits.

Publish your changes

How to create a pull request.

• Push your branch to your remote repository (fork):
  git push origin <my-feature-branch>
  If you are rewriting existing commits, e.g. after a rebase, you need to use --force:
  git push --force origin <my-feature-branch>

• Create a pull request. Log into GitHub and go to your fork. Locate the newly created branch. Press the button or link Pull Request on the top, besides the name of the branch. You will be given the option to review the pull request. Press the green button to Create Pull Request the Qucs project will receive your changes to be reviewed by the maintainers.

• Followup. Your Pull Request will be accepted or a reviewer will add comments to it. In case changes are needed, keep on modifying, committing and pushing to your branch <my-feature-branch>. The pull request will be updated automatically. You may be requested to rebase and/or squash your commits; see below for a quick guide about this.

Update your sources

The Qucs repository (upstream as mentioned above) is constantly being updated. It is good practice to always get the latest updates before branching off new work: use
git checkout [branch name]
to select the the branch of interest (e.g. develop), and
git pull upstream [branch name]
to sync your local branch with the Qucs branch.
There is no real need to keep your related branch on GitHub updated, but if you would like to, just use
git push origin [branch name]

Updating the qucs-test submodule

If you added some test to the qucs-test repository you may want to update the related submodule pointer in the qucs repository.

Since qucs-test is a submodule of qucs it does not point automatically to the latest commit in the qucs-test repository but it needs to be manually updated to point to the desired commit in qucs-test.

These are the basic steps:

• in a qucs repository clone, go to the qucs-test submodule directory
  cd qucs-test
• update the submodule with the latest content of the master branch
  git checkout master
• git pull
• go back to the main project
  cd ..
• git add qucs-test
• git commit

This will update the qucs-test submodule pointer to point to the latest commit on the master branch of the qucs-test repository.

More on Git

Rebase

When working with git, one often makes 'checkpoint commits', frequent commits to back up the work but captures the code in an unstable state. During the development, it is perfectly fine to have several commits where you just add some debug messages printout, try a new solution, etc., then other commits which just revert back these changes because you found a better solution. But when you finish your work it's important to clean up your code and leave a clean commit history. This makes easier to review your pull request and to understand the modifications you made. To do this, you take all the commits you've made on your branch and squash them into just a few commits - possibly just one, for simple modifications. Please check this guide to see how that works. As noted above, if you rewrite existing commits, you will need to use --force to update your remote.

If you just need to replace the last commit, do your modifications, stage the modified files as usual, then use git commit --amend

TODO: provide tips about common ways to use git to shuffle commits around and cleanup a branch.

Modifying old commits

If you need to modify old commits, because for example you spotted a typo or some bad formatting there, you can use git rebase.
If <base_commit> is the commit from where you would like to modify, run
git rebase --interactive <base_commit>^
then in the editor, modify pick to edit for the commit(s) you want to modify.
Exiting the editor, git will stop at the first commit marked for editing. Make your changes and then commit using
git commit --all --amend --no-edit
this will keep the same commit message used before. Then continue the rebase with
git rebase --continue

Cherry-pick

TODO

Stashing

If you need to save your current work to start working on other things and be able to resume later, you can stash your changes by using
git stash [save <description>]
Too save only unstaged changes use
git stash save -k <description>
To see the list of saved portions
git stash list
To retrieve the latest (and delete from stack)
git stash pop
To retrieve a specific stash and remove it from the stack
git stash pop stash@\{1\}
To view the content of the most recent stash, use
git stash show -p stash@{0}
To stash only certain files, use the interactive mode
git stash -p

Squashing commits

A pull request has usually several (maybe a lot of) commits. This is perfectly natural, but when the development cycle comes to its end, it is preferred to package all these commits into a single commit. This procedure is called 'squashing' and the steps to follow are:

• Use git rebase -i <my-feature-branch>~N to open the last N commits in your default text editor. The content should be something like:

 pick 415f03d Commit 1
 pick ce439cc Commit 2
 pick ca0efde Commit 3
 pick 9179e94 Commit 4

• Replace the words pick by squash (or just s) in the commits below the one you want to be the main commit:

 pick 415f03d Commit 1 
 s ce439cc Commit 2
 s ca0efde Commit 3
 s 9179e94 Commit 4

• Save and close the editor. It will automatically open again and there you can edit the final message of the 'composite' commit.
• Finally, you have to push these changes to Github:

git push origin <my-feature-branch> -f

where -f forces the pushing action

Rules about commits:

Please make sure that every commit is compilable; if any commit is not compilable, the entire pull request will not be accepted (in case you are wondering, the main reason is 'it will break git bisect')
Before you create the pull request, you can check your contribution using:
git rebase -i <root> --exec "make"
where <root> is the hash code or branch name where you start your contribution. If the rebase terminates normally, then there is no compiler error. If there are errors, please fix them.

Besides, it is strongly recommend that a commit message follows the "50/72 rule":

• First line (the header) should be 50 characters or less
• Then a blank line
• Remaining text should be wrapped at 72 characters

One-line messages (i.e. header only) are fine for small changes.

As detailed here and here, a good commit message looks like this:

    A 50 characters or less summary (use the imperative)

    The body of commit message: a few lines of text, explaining things
    in more detail, possibly giving some background about the issue
    being fixed, etc etc. The blank line separating the summary from 
    the body is critical.

    The body of the commit message can be several paragraphs, and please
    do proper word-wrap and keep columns shorter than about 72 characters
    or so. That way "git log" will show things nicely even when it's 
    indented.

    Make sure you explain your solution and why you're doing what you're
    doing, as opposed to describing what you're doing. Reviewers and your
    future self can read the patch, but might not understand why a
    particular solution was implemented.

Coding conventions

At present we do not have fixed Coding Conventions to be followed.

While we recognize that it will be good to have a uniform coding style, currently (June, 2015) our focus is not on this topic. Please refrain from altering the coding style of any section you did not have to modify anyway to fix a bug or add an agreed feature. This includes also altering newlines and spaces around. When adding new code, try to comply with the style of the surrounding code or - if you really can't stand it - use your own. Eventually, we will have code conventions and all the code will be reformatted, one day.

To quote from opengovernment:

Consider the people who will read your code, and make it look nice for them. It's sort of like driving a car: Perhaps you love doing donuts when you're alone, but with passengers the goal is to make the ride as smooth as possible.