InstructionCommitters

• Introduction
• Github flow
• Contributing additional tools, scripts, etc.

Introduction

The main advantage of the open-source software is that you may not only use it, but also modify it. We provide detailed instructions for modification of some parts of ADDA to add additional functionality on separate pages (see the section "Adding new ..." of the sidebar to the right), including, for example, adding new shapes and incident beams. However, you should not limit your efforts to these parts, if you are not afraid of somewhat larger complexity. You may also want to help the developers and fix some nasty bug in ADDA.

In any case, if you add code or change something in ADDA, please consider contributing your code to be incorporated in future releases. The rest of this page provides instructions for such contribution. Moreover, it is best to plan your contribution before the coding. In particular, please first search the issue tracker for the corresponding issue. If no suitable issue is found, submit a new one. A careful description of an issue with possible additions or changes from other developers is a key to easy incorporation of the new features into the main ADDA code. It is also recommended to study the structure of the existent code to better place your efforts.

Before you contribute your code, please try to make it readable and include enough comments, so the others may understand and modify it. There are many guides on good coding practices (see, e.g., 1 and 2), which to some extent contradict each other. A good idea is to adhere to the code style, which is already used throughout the code.

For large changes, better understanding of the code structure, and/or line-by-line debugging, an IDE (integrated development environment) can be very helpful. We had successful experiences with VS Code and Eclipse. It is easier to setup a project in the IDE, if it supports the make toolchain. However, successful use of Microsoft Visual Studio has also been reported. Any IDE usually includes a GUI interface to git, which will simplify the steps below, especially, for visualizing diffs (changes in the files).

By contributing the code, you naturally accept that it will be distributed under GPL 3 license. Additionally, please put a copyright notice in header of each new source file (which you created yourself). You can find example of such notice in any existing source file.

Github flow

We recommend the use of Github flow with addition of forking. In the following, we mention one variant for each step, while many more exist (through git command line interface or some GUI tool, online at Github, or through the dedicated tool gh). In particular, git command lines can be replaced by some mouse clicks. Note also that minor edits (including correction of typos) can be done directly at Github, either at your personal fork (see below) or, most simply, in the original repository. In the latter case, the fork and pull request will be performed automatically.

The following describes a workflow based on a separate branch and several commits inside it. The branch is the main atomic unit, which should implement a certain feature or a fix and will be reviewed as a whole. If several independent changes (that do not require or conflict with each other) are planned, repeat the following for corresponding number of branches. In principle, the same philosophy applies to individual commits (i.e., related change in several files should be in a single commit). However, it is fine to have the commits as small as you need, e.g., for testing or saving the intermediate progress. Specifically, if you forgot to include anything in the commit, just make another one right away.

• Create fork of ADDA by pressing Fork at top-right of the repository.

  • Alternatively, if the ADDA fork already exists in your account, sync its master branch (look for button Sync fork).

• Create branch with some branch-name.

• Clone the repository to your computer (user-name is your github account)
  git clone https://github.com/user-name/adda.git

  • Alternatively, if the local clone already exists, synchronize it by git pull inside the corresponding folder.

• Switch to the new branch
  git checkout branch-name

• Make one or several commits. For each of them:

  • Modify and create new files (and folders).
  • Test the implementation (compile and run ADDA, run various tests).
  • Verify modifications by git diff in the top folder (both the list of modified/added files and specific changes inside them). Some GUI tool (e.g., the one inside an IDE) will be helpful for any significant changes at this step.
  • Stage the changes (for all modified and added files)
    git add file.ext ...
  • Commit changes (large commit messages are welcome) git commit -m "descriptive message"

• Push changes to your Github fork by git push. Usually this is done once after all commits, but you may do it at any stage to show the intermediate state of the code to others.

• Create a pull request from this branch to the master branch of the main repository. For instance, press Contribute button at the right-top of your fork, when the proper branch is selected.

add here some details about pull requests process

• After the pull request is merged
  • Delete the branch. For a new change, create a new branch and repeat the above.
  • Your contribution will become visible at list of contributors.

Contributing additional tools, scripts, etc.

to be modified, mention examples

If you intensively use ADDA in your research, you probably have devised some tricks to make this process faster, more convenient, and less error-prone. Or you may have been so desperate to wait for implementation of a particular new ADDA feature that you devised a dirty but effective workaround. Either way, if you have something that anyhow enhances ADDA functionality, please consider sharing it with other users.

There is a special place in ADDA repository for this purpose – misc/ directory. It is distributed with ADDA but is not tightly integrated with the main code. The latter implies two advantages:

• Almost anything can be contributed: bash or python scripts, Windows *.bat files, source codes in C, Fortran, Matlab, Mathematica, etc., even binary executables.
• You do not need to worry about the future ADDA development and backward compatibility.

Of course, the amount of potential users of your tool depends on its portability (supported operating systems and whether it requires proprietary software to run) and amount of time you invested to polish the tool and its documentation. But even if you contribute the version, which you use yourself, it may benefit other people. The tool does not need to be perfect from the beginning. Moreover, as soon as you put your tool in the ADDA repository other people may also improve it.

The easiest way to contribute your tool is to give it as-is through the discussion group, issue tracker, or contacting developers directly. The developers will place your tool in an appropriate place inside misc/. We only ask that you include a short description of the tool, e.g. in a text file. Please also specify examples of usage and a particular version of ADDA, with which the tool was used (tested). If you have a relevant publication, in which your tool is described or used, include it in the description and ask others to cite your paper when they use your tool.

However, if you can invest a little bit more time, please consider becoming the official contributor. After that you can commit your tool directly and make any changes in the future. The additional effort required from you is quite small since you do not need to worry about interaction with other developers (branches, etc.). In other words, you directory inside misc/ is like a branch itself. The procedure is similar to the one described above, the only difference is that all changes are localized inside misc/ directory.

• Checkout the current misc/ directory

  svn checkout https://a-dda.googlecode.com/svn/trunk/misc/ --username <your username>
  

• Add a new directory for your tool

  cd misc
  svn mkdir <tool_name>
  

• Copy all the files relevant for your tool into misc/<tool_name>/
• Schedule new files for addition and commit everything (including directory <tool_name> itself)

  svn add <filename1> <filename2> ...
  cd ..
  svn commit -m "Contributed <tool_description> to misc/<tool_name>"
  

• Update affected documentation (wiki pages) and issues, especially if your tool provides some kind of workaround.

If you want to make any changes afterwards, just follow the instructions for minor changes while positioned in misc/<tool_name>/. Use of svn update may still be required before committing a new set of changes, even when changes of other developers (between your commits) does not affect misc/<tool_name>/ at all.