Contribute
Atomsk can still be improved in many ways. If you wish to help, then you may edit the source code to fix a bug, optimize a routine, add a new feature, and modify or add translations of the messages. You may also translate the documentation of Atomsk, so that users read it in their native language. Your contribution is welcome!
Report a bug
If you found a bug when running Atomsk, you may open an issue on GitHub, or contact the author by email.
A bug can be any behaviour that is not desired: a result that is incorrect or inconsistent, a bad translation, a crash or a segmentation fault. When submitting a bug report, please indicate the version of Atomsk you are using, and the command that produces the bug. Also if possible, explain what result you expected when running that command, and why you think Atomsk's behaviour is wrong.
Use Git and Github
Atomsk is developped using Git, and its development is made public on the platform GitHub. To learn how to use Git (the version management software itself), and how to use Github (the platform hosting Atomsk), the following links provide a good start:
Also, do not hesitate to ask your favorite search engine for more information and tutorials.
How to contribute to Atomsk
If you wish to contribute to Atomsk, follow these steps:
- Create your own account on GitHub.com. Please use your actual name (not a pseudonym).
- Go to the GitHub page of Atomsk and click the "Fork" button; this will create a copy of Atomsk on your own GitHub account.
- Clone this copy to your local computer (make sure you have Git installed and configured on your computer):
git clone https://github.com/my_name/my_repository
- Now, instead of working directly on the master branch (which can create conflicts), it is safer to create a separate branch:
git checkout -b my_branch
- Work on your own copy of Atomsk, modify the files to your liking. Compile your version to test if your modifications work. Don't forget to insert comments in your source code.
- Once your work is done, commit your modifications (with comments!):
git commit -a
Then, push them to your GitHub repository:
git push origin my_branch
Git will ask for your GitHub user name and password.
- Open your Web browser, go to the GitHub page of your repository, and click the "Pull request" button.
Your modifications will appear to the main author as a "Pull request". After reviewing your modifications, they may be accepted and merged with the main Atomsk (or not).
Send your modified version by email
Alternatively, if you cannot or don't want to use GitHub, you can send your modified version of Atomsk directly by email. In this case, please archive your whole modified copy (in zip or tar.gz format) before sending it. If possible or relevant, you may also send some example scripts to illustrate the changes you have made.
Important guidelines and good practices
Contributions are welcome. Contributions are good. However to avoid chaos, it is recommended to comply to the following guidelines when you contribute to Atomsk.
- Use your actual name and affiliation on GitHub. As the main author, I trust the commits more easily when I know where they come from. Even better: send me an email from your professional address when performing a pull request. Emails are always appreciated (see contact page). If you use a pseudonym or a non-professional address, your contribution will look suspicious, it will take more time to be reviewed, and it is more likely to be rejected.
- Contact the main developer before you start programming. It helps the main author to keep track of what is being worked on, so as to avoid that several people work on the same feature. You should either describe your intents by clicking the "Issues" button on the GitHub page of the project, or by sending an email to the main developer (see contact page).
- Comment and comment. Comment your source code. Comment your commits. Comments make it much easier to understand what was done, and make the review process faster. When there are no comments (or useless comments), the main author must spend time to understand the changes in the source code, why it was changed, and how it modifies the behavior of the program.
- Make sure that your version compiles before submitting a Pull request. If your version does not compile, then your work is not complete. Do not try to send your modifications, they will not be accepted!
- Make sure the documentation matches your modifications. Bug corrections do not require to modify the documentation. However if you modify existing features, or introduce new ones, then please also edit the documentation (in the folder /doc/) so that it takes your modifications into account. If your additions are not described in the documentation, virtually nobody will know they are there, and nobody will use them.
Version française
