1. How to contribute 1.1. Overview
1.2. Create your free GitHub account 1.3. Fork the repository
1.4. Clone your copy of the repository 1.5. Making changes
This book is licensed under the Creative Commons A ttribution-ShareA like 3.0 Unported License. Sharing of this work is encouraged.
1. How to contribute
In case you want to fix typos - there's bound to be plenty, edit this book or if you just want to add content to this book you can do so on GitHub. You need to have a GitHub account. Creating one is easy.
You will also need to install Git on your computer. There are Git installation packages available for many platforms. Once you have taken care of all that you should log in to GitHub and fork the repository of this book. A fterwards you can commit and push your changes to GitHub. When that is done you can send me a pull request. The next sections will discuss these steps in more details. There's also a page on GitHub dedicated to pull requests (the page however might be too elaborate.)
1.1. Overview
The idea is simple enough: you want to make a small or bigger change to the content of this book.
Problem: you don't have write access to the repository that holds this book's source code. You could send me an e-mail saying you would like to add this and that to such and such section. That's tedious.
A ctually you do have write access to this book's source code, in a way. This book's source code is hosted on GitHub, a site for collaborative sofware development. On GitHub once you have an account -it is very easy to fork a repos-itory. Once you've done that you can make any changes you like.
Forking is software development jargon for making a copy of a repository. Once the copy is made
this copy starts to live a life on its own but it still holds a reference to where is came from: the original repository. You can make changes on your copy of the repository - making these changes is called a commit - and you can then bring these changes to my attention. A lerting me of your changes is called a pull request.
I wil have a look at your changes. I might copy them entirely in the book. I might also make a few changes first. Or I might feel lazy and ask you to make some more changes before accepting your work into the book. In any case, when your changes make it to the book you will be listed as a contributor.
The following sections explain in more detail each step of this process.
1.2. Create your free GitHub account
Creating your free GitHub account is easy: go here and fill in your user name, e-mail address and password and you're done. To install Git on your computer follow this guide on GitHub.com. You follow that guide completely until the end (including the section on generating SSH keys and uploading your public key to GitHub.) If you skip steps in this guide you will not be able to complete the next steps.
1.3. Fork the repository
Visit the repository of this book and click the Fork icon in the top left corner of your screen. A fter a few moments a copy of the repository will have been created under your user name (check the URL.)
1.4. Clone your copy of the repository
Your copy of the repository only exists on GitHub for now. You can clone the repository which copies the repository to your computer. To clone your copy of the repository first copy the URL of your repository.
This URL will look like this:
[email protected]:username/BuildingYourOwn3DPrinter.git
The URL can be copied from the top of the page on GitHub. Once you've copied the repository URL open a command prompt on your computer and execute this command:
git clone <replace_with_repository_URL>
The git clone command will copy the repository from GitHub to your computer. You are now ready to make changes.
1.5. Making changes
This book is edited in DocBook format. DocBook is an XML notation for editing books. The files that make up this book are located under the src/main/docbook/en-USfolder. The files are named after the section titles of this book. If you want to fix typos you can edit these files with a regular text editor. You should use a DocBook editor if you want to make bigger changes to this document. I use the personal edition of XML Mind. XML Mind is written in Java and runs on Windows, Mac OS X and Linux. You can download the personal edition of XML Mind here. No registration or license is required.
To view your changes in HTML you can run this command:
For Windows:
gradlew publish
For Mac OS X and Linux:
./gradlew publish
This command will take a few minutes to complete. Once completed you can open the
appengine/index.html file to check your changes.
1.6. Commit your changes
Once you're satisfied with your changes you will commit them. Run this command in the folder where you've made your changes:
git commit -a -m "<Your comment here>"
You should use a comment that briefly describes the changes you've made, e.g. fixed typos. When you use an informative comment others will find it easier to parse through the list of changes made to this book.
1.7. Push your changes
When you've committed your changes you should push your changes to GitHub. Your committed changes are only visible on your own computer. By running the command below your changes will become visible on GitHub as well.
git push
Make sure this command completes without errors. When you do get errors first run this command:
git pull
Then run the git push command again.
1.8. Create a pull request
The last step in this process is to send me a pull request. Click the Pull Requst icon in the top left corner of your screen. On the next screen you will be asked to write a comment to accompany the pull request.
Briefly describe the changes you would like me to consider. Next click the Send pull request button below and you're done.
2. Similar efforts
There is a comparable effort to this one. It's called The Incomplete RepRap Beginner's Guide and it is maintained by COS.
3. Contributors
These people have kindly contributed to this book:
Kliment, spacexula, Mikko Kosonen, Nudel.
Copyright © 2011 Steven Devijver