diff --git a/chapters/how_to_contribute.md b/chapters/how_to_contribute.md index 2967b1026..1fc9ef9cb 100644 --- a/chapters/how_to_contribute.md +++ b/chapters/how_to_contribute.md @@ -12,7 +12,7 @@ Right now, I feel comfortable writing the text associated with each algorithm an In the future, I might allow other users to write algorithm chapters, but for now let's keep it simple: I'll do the writing, everyone else does the coding. Now for some specifics on submissions: -1. **Style**: Follow standard style guidelines associated with your language of choice. For C / C++, please use Stroustrup style, with `auto` used rarely or not at all. We have had plenty of discussions about this, which can be found [here](https://github.com/leios/algorithm-archive/issues/18). I will leave the issue open for now in the case that other individuals have more to contribute there. Basically, your code should be readable and understandable to anyone -- especially those who are new to the language. In addition, remember that your code will be displayed in this book, so try to keep to around 80 columns and try to remove any visual clutter. In addition, keep variable names clean and understandable. +1. **Style**: Follow standard style guidelines associated with your language of choice. For C / C++, please use Stroustrup style, with `auto` used rarely or not at all. We have had plenty of discussions about this, which can be found [here](https://github.com/algorithm-archivists/algorithm-archive/issues/18). I will leave the issue open for now in the case that other individuals have more to contribute there. Basically, your code should be readable and understandable to anyone -- especially those who are new to the language. In addition, remember that your code will be displayed in this book, so try to keep to around 80 columns and try to remove any visual clutter. In addition, keep variable names clean and understandable. 2. **Licensing**: All the code from this project will be under the MIT licence found in `LICENCE.md`; however, the text will be under a Creative Commons Attribution-NonCommercial 4.0 International License. 3. **CONTRIBUTORS.md**: After contributing code, please echo your name to the end of `CONTRIBUTORS.md` with `echo name >> CONTRIBUTORS.md`, and also leave a comment on the top of the code you submitted with your name (or username) saying `// submitted by name`. This way everyone is held accountable and we know who to contact if we want more information. 4. **Building the Algorithm Archive**: If you want to build the Algorithm Archive on your own machine, install gitbook and use `gitbook serve` in the main directory (where `README.md` is). This will provide a local url to go to to view the archive in your browser of choice. Use this server to make sure your version of the Algorithm Archive works cleanly for the chapter you are updating! @@ -32,4 +32,5 @@ Also note that depending on the algorithm, there might be in-text code snippets I'll update this page as the project grows. Basically, when you submit code, it will be under an MIT license. Please keep the code clean and put your name (or username) in the `CONTRIBUTORS.md` file. +If you would like to be a part of the ongoing discussion, please feel free to join our discord server: https://discord.gg/pb976sY. Thanks for all the support and considering contributing to the Algorithm Archive! diff --git a/chapters/principles_of_code/version_control.md b/chapters/principles_of_code/version_control.md index f68e846c4..c7703eb78 100644 --- a/chapters/principles_of_code/version_control.md +++ b/chapters/principles_of_code/version_control.md @@ -63,7 +63,7 @@ Because of this, you may want to create a repository under your own github usern ![How to fork](fork.png) Note that if you have a fork of a particular code repository, you can ask the owner of the original code repository to pull your changes into their version of the code with a *pull request*, but we are getting ahead of ourselves here. -If you cannot think of what repository to work on and want to collaborate on this project in the future, feel free to fork the [Algorithm Archive](https://github.com/leios/algorithm-archive) and modify that! +If you cannot think of what repository to work on and want to collaborate on this project in the future, feel free to fork the [Algorithm Archive](https://github.com/algorithm-archivists/algorithm-archive) and modify that! Regardless, as long as there is a repository under your username on github, we can continue by linking that remote github location to your local git directory. First, we need to find the url of the github repository, as shown here: @@ -77,7 +77,7 @@ Once you have the url, there are 2 ways to proceed: **The easy way:** ``` -git clone https://github.com/leios/algorithm-archive +git clone https://github.com/algorithm-archivists/algorithm-archive ``` **The not-so-easy way:** @@ -85,7 +85,7 @@ git clone https://github.com/leios/algorithm-archive mkdir algorithm_archive cd algorithm_archive git init -git remote add origin https://github.com/leios/algorithm-archive +git remote add origin https://github.com/algorithm-archivists/algorithm-archive git fetch git merge origin/master ``` @@ -95,7 +95,7 @@ For now, we will breifly describe each of the commands; however, we will definit So, here it is, step-by-step: 1. `mkdir algorithm_archive`: make a directory. We can call this directory anything, but we'll call it algorithm_archive for now. 2. `git init`: initialize git -3. `git remote add origin https://github.com/leios/algorithm-archive`: add a remote location (the github url we found just a second ago). Again, we can call this remote location anything, but `git clone` always calls it `origin`, so well stick with that. +3. `git remote add origin https://github.com/algorithm-archivists/algorithm-archive`: add a remote location (the github url we found just a second ago). Again, we can call this remote location anything, but `git clone` always calls it `origin`, so well stick with that. 4. `git fetch`: update the local directory with the information from the remote online repository 5. `git merge origin/master`: merge those updates. Right now, the `origin/master` part of this command might seem like a bit of black octocat magic, but we will cover it in just a bit! @@ -113,7 +113,7 @@ Actually, you probably were not asking that question. It's not an obvious questi The solution is simple: Add another `remote` like so: ``` -git remote add upstream https://github.com/leios/algorithm-archive +git remote add upstream https://github.com/algorithm-archivists/algorithm-archive ``` Obviously, you can call the remote anything. I kinda arbitrarily chose to call it `upstream`. By adding this in, you can easily interact with the same codebase from multiple remote locations. diff --git a/chapters/principles_of_code/version_control.md2 b/chapters/principles_of_code/version_control.md2 deleted file mode 100644 index 43f3e832f..000000000 --- a/chapters/principles_of_code/version_control.md2 +++ /dev/null @@ -1,197 +0,0 @@ -## Git and Version Control - -I am a fan of open-source software. It allows users to see the nuts and bolts of code running on their system and mess around with it if they like. -Unlike proprietary software, any user can learn everything about the software from the ground up, and that's an incredibly exciting prospect! -More than that, open-source development breeds strong communities of like-minded individuals who work together to solve problems they care about. -At least in my case, open-source software inspired me to code in my free time. It taught me that programming is more than a simple series of instructions for a computer. -More than anything, though, open-source software taught me about how to work with others and overcome petty squabbles, because if there's one thing the open-source community is known for, it's petty squabbles. - -It might be because of my appreciation of large-scale software development that I never questioned the utility of version control. -If you have a couple hundred people all contributing source code to the same place, there has to be some way to control all the different codebases individuals have on their own machines. -Even if I had no collaborators, version control was a way to make sure my laptop and work machine both had the same code without having to transer a USB stick back and forth. -That said, at some point in my life, I settled in as a physics researcher. -This meant that I wrote code to solve physics problems with a small team. The problem was that even though I was using version control, the rest of my team was not. - -This was frustrating. - I would hear my labmates say something like, "Yeah. I rewrote my code last night and now nothing works, but I already saved over my previous version, so I'll just work with what I have." -Or, "I'm writing a paper with my boss. We are using Dropbox and upload files with slightly different names after we modify them. Right now, we are on paper_78c." -The point is: version control exists to control different versions of software (and other documents). -If you are writing code, it exists as a way to quickly save what you have before making largescale modifications. -It also allows individuals to collaborate on a larger scale by providing necessary tools to merge work created by different individuals into a single, cohesive story. - -No matter how you look at it, version control is a useful and necessary tool to collaborate with other programmers and is definitely worth discussing in-depth. -Though many version control systems exist, for now we will focus on git, simply because it is incredibly popular and this book is hosted both on github and gitbook. -We hope to discuss other version control methods and strengthen the tutorial on git provided here in the future; however, this book is meant as an archive of algorithms, not as an introduction to version control or best software principles. -For now, this tutorial is simply meant as a quick way to kickstart our community into using git and collaborating more effectively on this book. - -I feel like this introduction may have been a little too long. Let me know what you think! Regardless, now it's time to talk about git! - -### *Git*ting started! - -As mentioned, this is not an exhaustive overview of how to use git for all version control purposes. -Instead, this is meant to provided the basics with the hope of providing our community a quick kick-start into collaborating effectively with version control. -I suppose let's start simply: git manages different versions of code available on different machines. -When using git, you will have a local copy of a repository of code that may or may not be up-to-date with a copy of the code repository in some remote location. - -Now, there is an easy way, a hard way, and an impossibly complicated way to use git. -We'll be walking through the hard way. It's not the most complicated way to set up a git repo, but it is the way that provides the most intuition on the topic. - -First things first, make sure git is installed on your system and set it up with the following commands - -``` -git config --global user.name name -git config --global user.email name@email.com -``` - -Obviously, use your own name and e-mail... unless your name is actually *name* and your e-mail is actually *name@email.com*, in which case the above commands are correct. -Remember that git is meant to facilitate collaborative code development, so we need to know who is submitting code so we can communicate more effectively later. - -Now we need to find a repository of code to work on. If you are starting your own repository or want to work on an internal network, this will not be too big of an issue. -If you just want to get the feel for how git works, I suggest going to [github.com](https://github.com/) and checking out the code developed there. -Note that you will not be able to contribute to any directory on github, simply because if anyone could contribute any code they wanted to any repository they wanted, the world would become incredibly chaotic. -Because of this, you may want to create a repository under your own github username or making your own copy of the code by going to any code you want to modify and clicking the *fork* button: - -IMAGE OF FORK - -Note that if you have a fork of a particular code repository, you can ask the owner of the original code repository to pull your changes into their version of the code with a *pull request*, but we are getting ahead of ourselves here. -If you cannot think of what repository to work on and want to collaborate on this project in the future, feel free to fork the [Algorithm Archive](https://github.com/leios/algorithm-archive) and modify that. - -Regardless, as long as there is a repository under your username on github, we can continue by linking the remote github location to our local git directory. First, we need to find the url of the github repository, as shown here: - -IMAGE OF CLONE - -Note that there are 2 provided urls here, one for ssh and another for https. From the user's perspective, the difference between the two is minimal: ssh requires the user to type only a password when interacting with the remote github repository, while https requires both a username and password. -Now, you will probably be interacting with github a lot, so ssh will definitely save time and is preferred for many people who use git a lot; however, [there is some initial set-up](https://help.github.com/articles/connecting-to-github-with-ssh/). -If you want, we can discuss the set-up in more detail later (just let me know!), but for now, we'll stick with https because it's more familiar to new users. - -Once you have the url, there are 2 ways to proceed: - -**The easy way:** -``` -git clone https://github.com/leios/algorithm-archive -``` - -**The not-so-easy way:** -``` -mkdir algorithm_archive -cd algorithm_archive -git init -git remote add origin https://github.com/leios/algorithm-archive -git fetch -git merge origin/master -``` - -Here, `git clone` does every step of the *not-so-easy* way in one command, so the two methods are completely identical. Because of this, in most cases, I just use `git clone`; however, the *not-so-easy* way is much more explicit and helps us understand what is going on a little better. -First, we make a directory. We can call this directory anything, but we'll call it `algorithm_archive` for now. -Then we go into the directory and initialize git and add a `remote` location: the github url we found just a second ago. Now, we can call this remote location anything, but `git clone` always calls it `origin`, so well stick with that. -We'll be discussing the final two commands a little later. For now, know that `git fetch` updates your local directory with the information from the remote online repository, and `git merge origin/master` merges those updates. - -No matter how you initialize your git repository, you will link your local directory with a remote location. If you ever want to see these locations, simply type: - -``` -git remote -v -origin git@github.com:leios/algorithm-archive.git (fetch) -origin git@github.com:leios/algorithm-archive.git (push) -``` - -This provides information on different `remote`s. We'll talk about `fetch` and `push` a bit later. -Now, you might be asking yourself: If I am only connected to the url I forked earlier, what happens when the owner of the main code repository pushes changes? How will I update my code when this happens? -The solution here is simple: Add another `remote` like so: - -``` -git remote add upstream https://github.com/leios/algorithm-archive -``` - -### Committing to git - -Now you have the repository linked to another online source. Note that you are not authorized to push changes onto the `upstream` url, but that's alright for now. Let's just stick to modifying `origin`. -At this point, we can make any modification we want! I might suggest doing something simple: - -``` -echo name >> CONTRIBUTORS.md -``` - -Nothing crazy, just something so we can get the feeling of git. To see what files have been changed, type: - -``` -git status -``` - -This will show that `CONTRIBUTORS.ms` has been modified. -If we want to save our changes, we need to add all of the files with changes to them to a package called a `commit`. -To add the files, simple type: - -``` -git add CONTRIBUTORS.md -``` - -Then if we type `git status` again, it will show that the file `CONTRIBUTORS.md` is in a *staging area* awaiting commit. This simply means that git is waiting to make sure there are no other changes we want to package up. -Now we create the `commit` by typing - -``` -git commit -m "Adding name to contributors file" -``` - -Note that if you do not use the `-m` message flag (just `git commit`), git will open your default editor (probably vi) to ask for a message. *Every git commit needs a git message!* Make the messages count. Be as descriptive as possible! -If you want to see all commits that have ever been made on this repository, simply type - -``` -git log -``` - -This will show you the history so far. As a side note, it also shows why good, clean commit messages are essential to managing large, open-source projects. -If there are hundreds (or thousands) of commits, and one of the features implemented somewhere down the line has a bug, clean commit messages allow us to find when the feature was implemented and possibly when the bug arose. - -Now let's say you want to checkout what the code looked like at a particular commit. To do this, we need to look at the generated unique string (SHA-1 checksum) associated with the commit we want and paste the first few (roughly 5) characters into the following command: - -``` -git checkout CHARS -``` - -It's incredibly unlikely that any two commits will share the first *n* characters, so this is unique enough for git to identify which commit we were referring to and send us back there, but here's where the notation get's a little crazy! -See, when we are sent back in time to the chosen commit (with the above command), we will be in a *detached head* state. -This refers to the term we use to describe the very latest commit, **HEAD**. -If we wanted to checkout the previous commit (for example), we would use `git checkout HEAD~1`, the second-to-last commit would be `HEAD~2`, and so on and so-forth. - -When we checkout another commit, we are rolling back the head of our commitment snake back to what it was in the past. -In the detached head state, we shouldn't really do any development. It's more of a read-only type of thing; however, if we want to develop the code starting at that commit, we could use - -``` -git checkout -b CHARS -``` - -But this requires a little explanation! - - -### Checkout these branches! - -Now let's take a step to the side and talk about another fantastic git feature, branches. -We have code forked under our own username on github. This means that there are at least 2 functioning versions of the code we are working on: our own fork and the original owner's fork. -That said, within each fork, there is the ability to have multiple lines of development, each one on a different *branch*. - -If you are new to software development, this might not seem to useful; however, imagine you are working on a large, open-source project that thousands of people use. -At some point, you want to re-organize a bunch of features in the code. -As a developer, you are not sure whether all the features you are re-organizing will still work properly after re-organizing them, but you know the code needs to be modified! -The problem is that you have users who may need the features you accidentally break. -For this reason, you might want to have a "master" branch -- one that is always working for the users, and a "development" branch -- one that is in the middle of creating new features for users. - -In truth, there are dozens of reasons why developers might want to work on slightly different versions of the code. -Rather than spending time outlining all the potential reasons, let's just dive into how branches are made and maintained. - -To check which branch you are on, simply type: - -``` -git branch -``` - -This will show you your currently active branch. If you haven't switched branches yet, you will probably by on `master`. -To switch branches, use - -``` -git checkout branch -``` - -And this will change all of the files on your local directory to match the branch you have swapped to. - - -### Pushing to github