Step by Step Instructions for Contributing to Singular - BrentBaccala/Singular GitHub Wiki

We describe the basic steps necessary to take part in the development of Singular. This applies both to contributions of libraries (written in the Singular language) and changes to the C Source code of Singular itself.

If you have written a Singular library and would like this to become part of Singular you can of course also email it to any member of the Singular team. However we encourage you to use the procedure described below, since this makes adding and reviewing future changes to your library much more easy.

1. Follow [the instructions to download and compile Singular from the latest sources in GitHub](Step by Step Installation Instructions for Singular#Compile from the latest sources in GitHub). If you only want to contribute a library the steps 1.a. (install git) and 2. (clone Singular) are sufficient.

2. Create an account on GitHub, if you do not already have one, and log in.

3. Go to https://github.com/Singular/Sources and create a fork of Singular by clicking the fork button.

4. Link your local installation of Singular (created in Step 1, we assume that you used the paths described there) to your personal fork of Singular on GitHub:

   a. Go to the directory where you cloned Singular:

   • cd
   • cd git/Singular4/Sources

   b. Add your personal fork of Singular as a repository:

   • git remote add myorigin https://github.com/yourgitusername/Sources.git where you replace yourgitusername by your git user name.

5. Update your local repository:

   • git pull --rebase origin spielwiese

     This step you may want to do every time before you do changes in your local repository.

     If you have other people contributing to your repository, you have to be careful with this step. For details see Instructions for contributing to private repositories.

6. Update your personal github repository:

   • git push myorigin spielwiese

7. Do your changes or additions in the directory Sources. New libaries, for example, go into the directory Sources/Singular/LIB.

8. Commit your changes locally (do this separately for changes which are not related):

   a. View your changes:

   • git status -uno

   b. Add your changes to git:

   • git add directory/filename if you changed or added the file directory/filename

   c. Commit your changes:

   • git commit -m "yourmessage" where yourmessage describes your changes.

9. Upload your changes to your personal github repository:

   a. Update your local repository:

   • git pull --rebase origin spielwiese

     If your local repository has changes which conflict with changes by another person, you will have to merge the changes. Please refer to a git howto, if this happens.

   b. Upload your changes:

   • git push myorigin spielwiese

     This step you may want to do regularily to have a backup of your work. Note that this only uploads changes which have been committed in step 8.

10. Test your changes:

    Every functionality should be covered by a test file.

    a. If you do changes to existing functions then you possibly can find the corresponding test files by git grep nameofcommand where nameofcommand is the name of the command you changed. They will be in the directory Sources/Tst.

    b. If you have added a new function you should also add a new test.

    1. Create a test file:

       It will usually go into Sources/Tst/Short. The filename extension is tst. It should have the following shape:

       • LIB "tst.lib";
       • tst_init();
       • Put your test commands here. They should reflect the complete functionality of your function. Do not forget boundary cases.
       • tst_status(1);$

    2. Install uuencode, for example in Debian you do

       • sudo apt-get install uuencode

    3. Create the reference output:

       • Be sure that the commands in your test file return the correct results.
       • cd
       • cd git/Sources/Singular4/Tst
       • regress.cmd -s $HOME/Singular4/bin/Singular -g Short/nameoftestfile.tst where nameoftestfile.tst is the name of the your new test file. The first path specifies the Singular binary used to execute your code.

       This you only do once, unless the behaviour of your function has changed.

       It will create two files nameoftestfile.res.gz.uu containing the output of your test commands in compressed form and nameoftestfile.stat with statistics. You should commit (see step 8) these two files and your test file.

    c. Run the test file and check for errors:

    • regress.cmd -s $HOME/Singular4/bin/Singular Short/nameoftestfile.tst where nameoftestfile.tst is the name of the test file.

    If you did more serious changes in the system, you can run all tests available at once on GitHub's continuous integration server

11. Create a pull request to ask for transfer of your changes to the main Singular repository:

    • log into GitHub
    • click on your username
    • click on Sources in the lefthand list (popular repositories)
    • click on compare in the header of the list of files to see your changes.
    • click Create pull request to open a pull request. Write a message which describes your changes and click Send pull request to finish.
    • GitHub's continuous integration system will run its test suite on the new pull request and email you the results
    • some people may start discussing with you in the instant messaging system of github about your changes. In this case you should be notified via email. You will also receive an email when your changes have been merged into the main Singular repository.