How to Contribute
In this guide you will learn step-by-step how to contribute to the Arcane Algorithm Archive (AAA). It seems to be quite long, but since it includes a lot of images and consists of small steps, it's easy and not too long to read. This page describes the steps of adding an implementation of an algorithm, but it gives much valuable information in general. So if you just want to make an edit, want to improve an implementation or something else, this page should still be useful.
If you encounter any questions or problems, feel free to hit us up on Discord.
So no more introduction and let's get started!
If you're already familiar with the git and GitHub workflow, you don't need to read the whole guide. It is sufficient, if you only read through and understand the following steps, which are AAA-specific:
- Step 1 - Getting the Tools set up
- Step 2 - Getting the AAA to run locally
-
Step 3 - Submitting Code
- Step 3.1 - upstream and origin
- Step 3.2 - Branching
- Step 3.3 - Adding code to your AAA-repo
- Step 3.4 - Committing
- Step 3.5 - Pushing (and pulling) to (from) GitHub
- Updating the master branch - explanation
- Step 3.6 - Creating a Pull Request
- Step 3.7 After the Pull Request: The Review
- Some Things to Keep in Mind
To download the AAA to your local machine and to take various other actions, you need to download Git. Git can be downloaded for basically every system right here: https://git-scm.com/downloads
The next thing we need is Honkit. It is the tool the AAA gets built with. By downloading it, you can do the same and therefore get the possibility to run the AAA locally.
Honkit can be retrieved via NPM. If you don't have NPM/Node.js installed on your system, you can download it here: https://nodejs.org/en/
After you downloaded and installed Node.js, you can go ahead and download Honkit with the following command:
npm install honkit -g
As the last part of Step 1 you can also try to set up your editor to accept an .editorconfig.
The .editorconfig is a file which holds certain rules for formatting files in different programming languages.
The AAA has its own .editorconfig made so that all files comply with a certain standard.
This page provides an overview showing the supported editors and, if necessary, links to extensions/plugins to support an .editorconfig: https://editorconfig.org/#download
Now that you have all the tools ready, it's time to create your own copy of the AAA.
This can be done by forking the AAA-repository.
To fork the AAA-repo, simply go to the AAA GitHub page and click the Fork button.
You just created your own copy of the AAA-repo as shown in this image:
Since you have your own copy of the AAA-repo on GitHub now, you just need to clone it to your machine. This will get your whole repo with its commit history (commits will be explained later) on your machine as well as some other things.
Cloning is pretty simple:
First you need to retrieve the URL of your AAA-repo. You can find it on the GitHub site of your AAA-repo as shown in this image:
After you got it, you just need to type the following command into your terminal and the AAA-repo will be cloned into your current directory:
git clone https://github.com/your-name/algorithm-archive.git
With this command you just did the following:
Once Git cloned the AAA-repo, you should see the following after navigating into the new directory (cd algorithm-archive) and running ls:
Now that you have the AAA-repo on your machine, you first need to get all the packages the AAA requires to build. This can be done by running:
npm install
After the all packages are downloaded, you can run/serve the AAA with this command:
npm run serve
Once the command finishes, your terminal should've printed out something like the following:
This indicates that you successfully built the AAA! You can check out your local AAA by navigating to http://localhost:4000 in your browser.
Here you can see the AAA, just like it is on algorithm-archive.org:
Before you start adding code or using Git branches, you need to set up your remotes to be able to update your local and remote (GitHub) AAA-repo.
Currently, you should have just one remote, the origin remote.
You can see your remotes by running:
git remote -v
And you should see the following output:
This means that you only have the origin remote:
This origin remote is a connection to your own AAA-repo on GitHub. This connection was automatically created by Git, when you cloned your AAA-repo.
But to be able to get the latest updates of the original AAA, you also need to have a connection to the algorithm-archivists' version of the AAA-repo on GitHub.
This other remote, where you can pull the latest changes from, should be named upstream.
So let's go ahead and add this other remote. You can do so by running:
git remote add upstream https://github.com/algorithm-archivists/algorithm-archive.git
Now you can print out your remotes again (with git remote -v) and you should see:
So your situation now looks like this:
You have all the remotes you need set up now, so you can update your local and your GitHub AAA-repo, by running the following three commands:
git checkout master
git pull upstream master
git push origin master
What exactly this does will be explained in Step 3.5.
Now you're able to update your local and GitHub AAA-repo by just running three commands.
All you worked with until now is the so called master branch.
This branch should always stay up-to-date to upstream and shouldn't be manually changed by you.
That's why you need to create your own branch whenever you want to add code or similar stuff to the AAA-repo.
Your local AAA-repo as well as your GitHub AAA-repo and the algorithm-archivists' GitHub AAA-repo have this master branch as shown in this image:
See it like this: The master branch is mirroring the current state of the AAA.
You don't want to destroy this mirror by adding your own code to it. That's why you need to create your own branch.
If you, for example, wanted to add an implementation of an algorithm in Python, you would do the following:
git branch chosen_algorithm_in_python
This command just created a new branch with the name chosen_algorithm_in_python.
The following image shows the new branch (here called otherand in red):
However, you're still on your master branch.
To switch the branch, just type:
git checkout chosen_algorithm_in_python
The little arrow (also marked in red) indicates that you now switched to the chosen_algorithm_in_python (here other) branch - you checked out this branch:
Here you can change the files you need to change so that the AAA can get an Python implementation of the chosen algorithm.
What exactly you need to change and all further steps like how to get your branch merged (i.e. get the stuff from your new branch into the master branch) will be described in the following steps.
First of all, there are some things you need to know before you start adding your code:
- Only implement algorithms that are already in the AAA. Don't just add (and later submit) code that's not implementing an existing algorithm. This code is not needed (for now) and the submissions (Pull Requests) will just get closed.
- Take a look at the page of the algorithm you want to implement. Look whether there are any code snippets (for example ones that show off functions) and make sure that your final code has these code parts as well. (If your language has a special behavior and you have no idea what you should show there, just leave it open and mention it later in the submission (Pull Request)).
- Make sure that you don't work on something that another person already works/worked on. If you don't want to improve existing code but want to submit a new implementation to the AAA, take a look at the page of the algorithm you want to implement to see whether or not it's already in the AAA. Also take a look at the Pull Requests (looking for the algorithm you want to implement and the language you choose) to make sure that no one already submitted an implementation of it. You can, of course, always implement algorithms just for your own joy or improve existing code and submit that (in a Pull Request).
-
Only one language and one algorithm.
Each submission (Pull Request) should only include the implementation of one algorithm in one language.
You can, of course, do more languages and algorithms, but you need to create a new branch for every new implementation you want to add. (This can be achieved by running:
git branch your-branch-name master. This will create a new branch based on master. Make sure to update your master first.)
After reading the notes above, you can start adding your code to the AAA.
First, you need to identify the algorithm you want to add code to.
If you want to add some code for Bubble Sort, the directory of your interest is the bubble_sort directory which can be found at algorithm-archive/contents.
In this directory, you first need to create a new code directory for your language at algorithm-archive/contents/chosen-algorithm/code. The name of the code directory should be the name of the language and all lowercase (interesting cases are: C++, which has c++, and C#, which has csharp).
After you created the new directory for your code, you can simply add all code files of the algorithm implementation.
A correct directory structure should look like this (let's imagine you added Bubble Sort - Python):
Now that you added all the files to the new directory, your code is in the AAA, but it doesn't show up.
What you need to do for it to show up is fairly simple.
First, open the markdown file of the algorithm (.md).
There, you need to identify all instances of:
{% method %}
// code in multiple languages is imported here
{% endmethod %}
The instances mark places where code gets imported into the page.
The very last place should import all files you created.
The other places often just target specific functions (for example just a Sort() function as an explanation, but not all other code).
To identify which exact function is needed, run the book (described in Step 2.3) via npm run serve and go to each code example.
In this image you can see which code imports correspond to which code examples (here: Euclidean Algorithm with Python code):
So for each of these places where code gets imported, you need to add the following above the {% endmethod %} of each place:
{% sample lang="multLangIdentifier" %}
[import:maybeLineRange, lang="highlightIdentifier"](path/to/code)
The multLangIdentifier is important for Honkit to provide the language switcher that you see at the top of the algorithm pages.
The multLangIdentifier is simply the file ending of the language you want to add.
If you add a new language to the AAA, there is no
multLangIdentifierexistent for it yet. Please take a look at thebook.jsonlocated at the root of the book and add the following quite at the end of the file:{ "lang": "abbrevation_of_your_language", <- should be all lowercase "name": "name_of_your_language" <- will be displayed on the website }For example:
{ "lang": "py", "name": "Python" }Please don't forget to add a comma after the last curly bracket of the previous entry. The
abbrevation_of_your_languageis then themultLangIdentifieryou need.
The highlightIdentifier is another story though.
Here, you can either look at the existing code imports of your language to identify which highlightIdentifier you need.
Or you can just look at the following overview: https://prismjs.com/#languages-list and grab the identifier of your language.
If you can't figure out what to input or it just doesn't work, leave the highlightIdentifier blank and mention your issue later in the submission (Pull Request).
So, importing Python into the markdown file of the Euclidean Algorithm looks in the first two places like this:
{% sample lang="py" %}
[import:11-22, lang="python"](code/python/euclidean_example.py)
and
{% sample lang="py" %}
[import:1-9, lang="python"](code/python/euclidean_example.py)
And in the last place, where no line-ranges are needed, it looks like this:
{% sample lang="py" %}
[import, lang="python"](code/python/euclidean_example.py)
Now you can run npm run serve again (or just let it rebuild automatically, if it is still running) and look at the page of the algorithm you're targeting.
You should now be able to select your chosen language at the top and you should see your code in all places where code examples should be.
If that's not the case and something went wrong, please check that you imported everything in the correct way. If problems still exist tho, feel free to contact us on Discord.
Since your code is now in your local AAA, it's time to commit your changes. Committing basically means: "These changes, additions, and deletions I made, I want to save".
First of all, it's good to get an overview of the changes you made.
You can get an overview by running git status.
Here you should see the names of the files you modified and the name of the code directory you added.
If that's not the case, please contact us on Discord and describe your situation.
If that is the case, you can run git add -A.
This command adds all changes you made.
That means Git knows that you want to commit all the files you just added (in this case all modified files).
If you added your language to the
book.jsonsince it wasn't in the AAA before, you can make two commits to separate the addition of the language to thebook.jsonfrom the other changes. This can be done by runninggit add book.jsonat the first level (algorithm-archive/) of the repository and then committing as described in the next few sentences.After you've done that, you can just commit the other changes as described in this Step.
Now as a last step you can run git commit -m "msg".
Instead of writing msg, you should add a little explanation describing what this very commit changes, so other people (or you in the future), know what you did at that point in time.
Make sure to put the message in quotes to avoid problems.
After you ran this command, you just committed your changes to your local branch:
If you make modifications in the future, simply create a new commit the way described above.
Now that you made your first commits, you also need to push them to GitHub. This is fairly simple. First you need to run:
git push --set-upstream origin your-branch-name
After running that, you'll just need to insert your credentials and Git will push your branch and its changes to GitHub and set up the default remote; Git pushes and pulls from (origin).
This means that you have your branch and latest commit(s) now on your fork of the AAA-repo on GitHub:
Since all that is set up now, you can easily push changes to GitHub, by running
git push
and you can retrieve changes from GitHub (e.g. when you pushed changes to GitHub from another computer) by running:
git pull
Just make sure that you're currently on the branch you want to push, by running git status.
Now you can also understand what the three commands you use to update your master do:
The first commands makes sure that you're on the master branch. You're checking out the branch:
git checkout master
The second command then pulls (downloads) the latest changes from the master branch of upstream and updates your local AAA-repo:
git pull upstream master
And the third command finally pushes (uploads) these new changes to the master branch of origin (your fork of the AAA on GitHub):
git push origin master
Now that you followed all the steps that enable you to properly use Git to add implementations to the AAA, just one thing is left: The Pull Request.
A Pull Request is basically a request to the main AAA (i.e. the algorithm-archivists' AAA) to merge one of your branches into one of the algorithm-archivists' branches of the AAA. In your case, it's a request to merge the branch you created with your new implementation into the master branch. This is the way your code can get into the AAA and appear on algorithm-archive.org.
In this graphic you can see what connection a Pull Request is:
So, let's create a Pull Request!
First of all, you need to navigate to your GitHub fork of the AAA. There you can click one of the buttons shown in this image:
After clicking one of these buttons, you need to make sure that the right branches are selected.
You can see that in the following image: On the left side, algorithm-archivists/algorithm-archive and master should be selected and on the right side your-name/algorithm-archive and name-of-your-branch.
If the right things are selected, you just need to click the Create pull request button:
Now you're given an interface where you can insert a title and a description for your Pull Request. For the title, you should choose a descriptive one. If you implemented Bubble Sort in Python for example, you should create a title saying "Bubble Sort Python Implementation".
Then there's also the description. If you encountered a problem, have a question or would just like to say something, you can put it here. If you don't, just leave it empty.
After you entered everything, you can go ahead and click the Create Pull Request button.
With the press of this button, you just created a Pull Request! Congratulations!
Your Pull Request is now created, and after some time, someone will start reviewing the Pull Request and point out flaws, concerns, and questions that occur.
It's not a bad thing, if we request changes and ask for improvements, we want improve your code and help you!
So, after someone reviewed your PR, you can just go ahead and correct the things the person pointed out.
Doing that is fairly simple.
Just checkout your branch locally (via git checkout your-branch-name), make corrections, run the book to check that everything is correct (via npm run serve) and then finally push the changes to your branch (via git push).
Since the PR uses your branch, the changes immediately show up after you pushed them.
This review cycle then goes on until the reviewer is happy. If they are, they will approve your Pull Request and merge it. Then your code is part of the algorithm-archivists' AAA-repo and will therefore show up on the site (after a few minutes).