ea-tel / detel-book

DE-TEL Book

Welcome to the editing environment for the DE-TEL Book.

How To Run Locally

Prepare Development Environment

Step 1. Install Ruby on your machine (Detailed instructions)

If you are going to install Ruby on a Windows machine, there is a convenient tool RubyInstaller.

Ruby version 2.7.5 is recommended to work with this repository.

Step 2. Check that Ruby is successfully installed and can be accessed from the terminal / command line. To do this, open the Command prompt and run command:

ruby -v

It should return the installed version of Ruby.

On Windows, you can find an entry called "Start Command Prompt with Ruby" in your start menu after the installation. It makes sure that Ruby is accessible by that command prompt. If the default command prompt cannot find Ruby, you can keep using this special command prompt.

Step 3. Clone this DETEL book repository. If needed, use instructions of how to clone a GitHub repository. Remember the folder where the local version of the repository is stored on your machine.

Step 4. In the terminal/command line, navigate to the folder with the local version of the DETEL book repository. To navigate to the correct folder, use following command:

cd foldername

Example of how to use the cd command:

When you open Command Prompt, you see a line similar to this:

C:\Users\username>

You can type these commands to navigate:

C:\Users\username>cd Documents
C:\Users\username\Documents>cd GitHub
C:\Users\username\Documents\GitHub>cd detel-book

Now you are in this directory:

C:\Users\username\Documents\GitHub\detel-book>

You can also type the entire path after cd:

    C:\Users\username> cd C:\Users\username\Documents\GitHub\detel-book

Step 5. Install bundler

Run the following command:

gem install bundler

NB: In Windows 10, you probably are better off installing a particular version of bundler

gem install bundler:2.1.4

Step 6. Use bundler to pull Jekyll

Run the following commands (make sure you run them from the /detel-book folder, as per Step 4 above):

bundle install

bundle update

Build & Serve Locally

First, please change the _config.yml "url" parameter to "http://localhost:4000".

Please do not commit this change! Now build the page locally with the following command:

bundle exec jekyll serve

Navigate your browser to http://localhost:4000/detel-book/ to check results while you develop.

How to branch and create a pull request

Now when you have the writing environment setup locally, you can start creating new or change existing content. We recommend that you work on one piece at a time, as it will be easier to review your contribution. Please, follow this process:

Step 1. In GitBash, navigate to the folder with the local version of the DETEL book repository.

You should notice that Gitbash displayed the name of your current branch in parentheses after the name of the directory. It is (master) by default.

Step 2. Create a new branch

$ git checkout -b "MyNewBranch"

You should now notice that GitBash has switched to your new branch.

Step 3. Edit!

Now, you can create, edit or delete any content of the book. For example, you if you want to create a new chapter, you can create a new file and start editing it. You can use any text editor, like a Notepad app, to edit the file. However, we recommend that you install and use VS Code app. This app is free and has several convenient tools in addition to editing the text itself.

The content of the book is written in Markdown, a simple markup language. To get started with Markdown, check this starting guide and this cheat sheet.

Step 4. Submit your edits for review

After you have made a set of edits, you need to run the following commands in GitBash to submit your changes for review in the online repository:

Add all your changes to the submission:

$ git add -A

Create a commit:

$ git commit -m "Short human-readable description of the changes I made should be written here"

Send the commit to the online repository:

$ git push

Step 5. Wait for review

Now you can wait for one of our administrators to check your contribution and accept or reject it. As soon as it is accepted, the contents of your commit will appear online on the public website.

While you are waiting for the review, feel free to work on the next set of edits (e.g., your next chapter). You should start new unrelated work (e.g., another chapter) on a new branch and that this new branch must be based on the master branch.

Template Chapter

To make creating chapters more accessible and easier for contributors, a template chapter is provided here which can be freely copied and used to create your own chapters. In this template chapter you can find extensive explanations about everything necessary to correctly format your chapter in Markdown and integrate it into the structure of the book.

Description

Scope

Contents

Contribution Model and Technical Infrastructure

The book project follows an agile approach differing from the classic development process typical for printed content. Contributors can play several different roles in the production process. We are looking for authors, reviewers, agile editors, designers, software developers, visual artists, and testers. Agile teams are responsible for the generation of chapters and act as product owners.

• Reviewers will review chapters and communicate with the author teams.
• Team champions drive forward the agile development of chapters.
• Designers lay-out the online book and printed versions.
• Software developers are responsible for interactive Web graphics, application examples, exercises and other dynamic code.
• Visual artists are responsible for appealing visualizations.
• Testers will thoroughly try out the final versions of the book.

The book uses Git for version management and a GitHub organization for the creation, hosting, and delivery of the book contents to guarantee agile development. We use the GitHub-based issue tracking system for the communication between the community members, such as the authors and the reviewers. Based on this content sharing and version management platform we use the static site generator Jekyll for rendering the content of the Git repository into a Web site. With every commit, a new version of the Web site is created automatically. Formatting of the content is done using a simple markdown language. Programming and lay-out uses JavaScript and CSS.

The project's wiki contains further details about the contribution guidelines and the technical environment.