Contributing your algorithm to the package
If you want to contribute your algorithm implementation to the high-dimensional-sampling (hds) package, we recommend you follow the steps laid out in this manual. The package is maintained using the Github workflow, also following this workflow has some notable benefits:
-
A system has been set up for the hds package that checks the code for its functionality at each code change. In other words: if you follow the steps, you can be sure that you did not accidentally break the code.
-
Part of the Github workflow is that your code is checked by one of the package maintainers. Checks are done to make sure your code can be understood by independent readers and to make sure that no non-critical errors slipped in.
Even though the workflow has these benefits, we can imagine that the workflow can be a bit complicated if you are not used to it. This manual lays out the workflow as extensively as possible to mitigate this possible problem. If you nevertheless encounter any problems, don't hesitate to contact the package maintainers!
The workflow consist out of the following steps. A complete description of each of the steps, including guides on how to execute them, can be found below.
-
Step 0: Make sure that the maintainers are aware of the change you want to make to the package. You can do this by opening a Github issue at the issues page. This invites discussion from the maintainers and other stakeholders. Don't skip this step, as it might happen that your change might be declined by the maintainers. Only continue when a consensus on your suggestion is reached.
-
Step 1: Copy the code to your own personal github account, where you can make all the changes to the code that you want. This is called forking.
-
Step 2: Create a local copy of the repository on your computer. This is called cloning. This manual will present two ways on how to do this: via a terminal / console and via the Github Desktop app.
-
Step 3: Make the changes that you want to make to the code, e.g. adding your own algorithm to the implementation folders
optimisationorposterior. -
Step 4: Store the changes you made to the code in the local version of your repository via the terminal / console or the app. This is called committing your changes.
-
Step 5: Use the terminal / console or the app to send the changes you made to your Github account. This is called pushing your changes.
-
Step 6: Request the maintainers of the package to implement the changes you made to your copy of the package in the official package code. This is called making a pull request.
For those of you who are already (kind of) familiar with Git or Github: this manual will not include explanations on how to use branches within the repositories. This choice was made for simplicity of the manual. Feel free however to use branches if you know how to used them!
In order to make changes to the package, you a need a version of the package that you are allowed to make changes to in the first place. Github allows you to download the entire repository to a .zip file, but this also decouples your copy of the code from the official package code. The whole idea of the workflow is that when you have made your changes, the code maintainers can have a look at your code and can merge your code changes into the original package code. In other words: don't download the code as a .zip file.
Then, what should you do? Instead, go to the
Github page
of the package and on the top right, click the fork button.
If asked, select your personal account as location to fork the code to.
You should now have a copy of the repository in your own account. You can
access it by going to http://www.github.com/.../high-dimensional-sampling,
where the ellipses should be replaced by your github username. The title of
the package indicates that it is a fork of another repository through the fork
icon in front of it and the name (with hyperlink) of the original package
below it.
Now that you have your own copy of the code, let's make a local copy of it so that you can start making changes to it. We will cover two ways of doing this here: through a terminal or console, and through the Github Desktop app. Although the Desktop app works properly, we recommend you to use the terminal approach if you are familiar with the terminal.
Regardless of the approach you need a very specific URL of the package in order to be able to clone it. You can find this URL by going to the Github page of your own copy of the code and clicking the green button. Copy the URL that is shown there.
It is noteworthy that a lot of IDEs nowadays have Git, and even Github, integrations built into them, allow you to do everything from the IDE itself. The three most popular IDEs (VS Code, Sublime and Atom) all have this integration or can be extended with this integration. We won't cover how to use those there, but if you are interested, it might be worthwhile looking into.
Terminal / console: Navigate to the folder where you want the local copy of
the code to appear. You don't have to create a new folder for this, when
cloning your repository all code will be placed in a new
high-dimensional-sampling folder that will be created in the cloning process.
You can clone the repository by typing the following command:
git clone ...
in which you replace the ellipses with the URL you copied from the Github page. You will get a request for a password. This should be the password you use on Github. Type in the password and the repository will be copied to your local disk.
It might happen that you get an error saying something in the lines of "Permission denied (publickey)". In that case you can do either of two things to solve it:
-
Use HTTPS instead of SSH to connect with the Github servers. For this, click the
Use HTTPSlink in the top right of the dialog box from which you copied the URL and use the https-URL that appears instead. -
Follow the manual at this url to add an SSH-key to your Github account. After following all the steps in this manual, you should be able to clone the repository.
Github Desktop app: You can download the Github Desktop app from their official website. Open the app after downloading and click the "Clone repository from the internet" button.
In the dialog window that opens, paste the URL that you copied above. Note the
text in the Local Path text line below. This is the location to which the
local copy of your code will be saved. If you are okay with this location, or
have changed this location to another location of your liking, click the blue
Clone button.
At this point you have a local copy of the code and you can make any change to it that you want. Don't worry about breaking the package itself, you are editing a local copy of your personal copy of the package.
When you want to add your own algorithm to the package, the main thing you
have to ask yourself is whether your algorithm is an optimisation algorithm
or an algorithm for posterior sampling. If it is the former, place your
algorithm in the folder high-dimensional-sampling/optimisation, if it is the
latter place it in high-dimensional-sampling/posterior. Make sure that your
algorithm is a child class of the
high_dimensional_sampling.procedures.Procedure class, as otherwise it will
not work with the package!
After having done this, you should make one last change to the __init__.py
file located in the same folder as your algorithm (so either the posterior
or optimisation folder). Add the following line at the top of the file:
from .filename import Classname # noqa: F401
where you replace filename by the name fo the file that contains your
algorithm and Classname by the name of the class that contains your
algorithm. This change ensures that users can easily find and access your
algorithm.
Now that you made changes to the code, you need to let the repository know which changes you made. This might feel a bit weird (why would you need to do this, apps like Dropbox and OneDrive know perfectly well which changes I made without me telling them), but it allows you to work on multiple files at the same time, but labeling specific changes to belong to a specific update of the code.
Terminal / Console: You can see which files are changed or added within the local repository by going to folder and executing the following command:
git status
You can add files from this list to the commit by executing
git add ...
where you replace the ellipses by the location of the file (both absolute and relative paths work). You can add all changes with
git add .
If you are confident you added all necessary files to the commit, you can label all changes in one single commit with the following command.
git commit -m ...
Replace the ellipses in this command with a short explanation of what the changes you made entail. This is useful for future reference: instead of having to look at the code and the changes to the code, the commit message contains information on what the changes are.
Desktop Desktop app: Open the desktop app. On the left a list of all
changed files will be shown. Make sure that only the checkboxes in front of the
files that you want to add to this commit. Below the list, add a title to your
commit and a short description. When all is done, click the blue commit to master
button below the description field.
So far you have made your changes and grouped them together in a commit. You can continue this process, including more and more commits in your local repository. When you have made all the changes you want to make, you need to send those changes to the repository on the Github servers.
Terminal / Console: To push your changes to the Github servers, execute the following command.
git push
Github Desktop app: In the black bar on the top of the app screen, click the last button saying something like "Push changes".
The changes you have made so far are made to your personal version of the code. Yes, your changes are located on your local disk and on the Github servers, but remember that you pushed them to your personal version of the package repository. If you are happy with all the changes that you made and pushed to the server, you need to notify the maintainers of the package that you have some changes that you want to be included in the package.
In Github slang this is called a pull request: you request the maintainers of the package to pull the changes from your personal copy of the repository to the official code.
To make a pull request, go to the Github page of your personal copy of the
package and click the New pull request button.
On the page that now appears add a description to your pull request in which
you describe what your changes do to the package. When content with your
request, click the green button Create pull request.
Congratulations! You just walked through the entire Github workflow! After you clicked the green button, a couple of things automatically happened:
-
The maintainers of the package got notified of your request.
-
The code with implementation of your changes is automatically checked for its workings.
The maintainers will have a look at your code and when they have questions, they might contact you through the page of your pull request. You can view this page at the pull request list.