Do you want to fix a bug, optimize a routine, add a new feature, or add translations for Atomsk? Your contribution is welcome!
Send your files by email
If you modified an existing file of Atomsk, or if you developped a new one, you can send your modified version directly by email. Please archive your whole modified copy of Atomsk (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.
Use Git and Github
Alternatively, a more robust and practical way to share your modifications is to use a version management tool. 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.
Get the development version of Atomsk
If you just wish to download the latest development version of Atomsk, then create a directory on your computer and type the following command:
git clone https://github.com/pierrehirel/atomsk
Beware, however, that this version may contain features that are not completely implemented, bugs, or may even not compile or not work at all. Use it at your own risks.
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).
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.