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, which naturally support 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. ADDA developers with write access to the main repository can skip the forking, but otherwise the workflow is the same. 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 console commands can be replaced by mouse clicks in a GUI. 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 changes 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 directory.

• Switch to the new branch
  git checkout branch-name

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

  • Modify and create new files (and directories).
  • Test the implementation (compile and run ADDA, run various tests).
  • If files are added or removed, update the README.md in corresponding directories (which have short descriptions of directory contents).
  • Consider if any other changes to the documentation are required. If you update the manual, please use Track changes in the docx file.
  • Verify modifications by git diff in the top directory (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.

• Read carefully and fill the provided checklist (at pull-request description). It repeats many of the above items.

• After the pull request is submitted:

  • Wait for feedback from one of ADDA maintainers
  • It may require several iterations of additional changes
  • Finally, it will be merged

• 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.

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.

While you can host the tool anywhere and give a link through the discussion group or issue tracker, the recommended approach is to follow the above procedure with the only difference that the changes are limited to misc/ directory instead of src/ one. 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.

The same applies to ADDA examples, where additions are always welcome. See the corresponding README.md and those in child directories for details. Other directories (e.g., tests/) are also open to contributions - it is open source after all!