Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fixed environment docs for recent Ubuntu versions #4034

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Fixed environment docs for recent Ubuntu versions #4034

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cc8bf98
Fixed environment docs for recent Ubuntu versions
May 1, 2023
a495a2f
Fix "working with Github" header markdown
May 1, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
48 changes: 35 additions & 13 deletions docs/setting-up-your-environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
## Setting Up Your Environment
# Setting Up Your Environment

#### Preview Small Text Changes
## Preview Small Text Changes

Simple text changes can be previewed live on bitcoin.org. You only need to click
anywhere on the page and hold your mouse button for one second. You'll then be
able to edit the page just like a document. Changes will be lost as soon as the
page is refreshed.

#### Build The Site Locally
## Build The Site Locally

For anything more than simple text previews, you will need to build the
site. If you can't do this yourself using the instructions below, please
Expand All @@ -19,19 +19,19 @@ To build the site, you need to go through a one-time installation
procedure that takes 15 to 30 minutes. After that you can build the
site an unlimited number of times with no extra work.

##### Install The Dependencies
### Install The Dependencies

Before building the site, you need to install the following
dependencies and tools, which are pretty easy on any modern Linux:

**Install binary libraries and tools**
#### Install binary libraries and tools

On recent versions of Ubuntu and Debian, you can run the following
command to ensure you have the required libraries, headers, and tools:

sudo apt-get install build-essential git libicu-dev zlib1g-dev

**Install RVM**
#### Install RVM

Install RVM using either the [easy instructions](https://rvm.io/) or the
[more secure instructions](https://rvm.io/rvm/security).
Expand All @@ -42,7 +42,7 @@ following command:

source ~/.rvm/scripts/rvm

**Install Ruby 2.5.8**
#### Install Ruby 2.5.8

To install Ruby 2.5.8, simply run this command:

Expand All @@ -52,6 +52,23 @@ Sometimes this will find a pre-compiled Ruby package for your Linux
distribution, but sometimes it will need to compile Ruby from scratch
(which takes about 15 minutes).

If Ruby 2.5.8 fails to install with a `make` error, you likely need to install an older version of OpenSSL that is compatible (source for these instructions can be found [here](https://github.com/rbenv/ruby-build/discussions/1940#discussioncomment-2663209)):

sudo apt install build-essential checkinstall zlib1g-dev
wget https://www.openssl.org/source/openssl-1.1.1q.tar.gz
tar xf openssl-1.1.1q.tar.gz
cd ~/Downloads/openssl-1.1.1q
./config --prefix=/opt/openssl-1.1.1q --openssldir=/opt/openssl-1.1.1q shared zlib
make
make test
sudo make install
sudo rm -rf /opt/openssl-1.1.1q/certs
sudo ln -s /etc/ssl/certs /opt/openssl-1.1.1q

After this older version of OpenSSL is available you can install Ruby 2.5.8 with the following command:

rvm install 2.5.8 --with-openssl-dir=/opt/openssl-1.1.1q

After Ruby 2.5.8 is installed, make it your default Ruby:

rvm alias create default ruby-2.5.8
Expand All @@ -60,20 +77,25 @@ And tell your system to use it:

rvm use default

Validate that your default version of Ruby is now `2.5.8` (the exact minor version might not match, but should start with `2.5.8`):

ruby --version
ruby 2.5.8p224 (2020-03-31 revision 67882) [x86_64-linux]

(Note: you can use a different default Ruby, but if you ever change
your default Ruby, you must re-run the `gem install bundle` command
described below before you can build the site. If you ever receive a
"eval: bundle: not found" error, you failed to re-run `gem install
bundle`.)

**Install Bundle**
#### Install Bundle

When you used RVM to install Ruby, it also installed the `gem` program.
Use that program to install bundle:

gem install bundle

**Install the Ruby dependencies**
#### Install the Ruby dependencies

Ensure you checked out the site repository as described in [Working with
GitHub](https://github.com/bitcoin-dot-org/bitcoin.org/blob/master/docs/working-with-github.md).
Expand All @@ -91,7 +113,7 @@ long time to install on some systems, so be patient.

Once Bundle completes successfully, you can preview or build the site.

##### Preview The Site
### Preview The Site

To preview the website in your local browser, make sure you're in the
`bitcoin.org` directory and run the following command:
Expand All @@ -107,7 +129,7 @@ message like this:

Visit the indicated URL in your browser to view the site.

##### Build The Site
### Build The Site

To build the site exactly like we do for the deployment server, make
sure you're in the `bitcoin.org` directory and run:
Expand All @@ -126,7 +148,7 @@ directory. The following alternative options are available:
## Or build the site and run all tests
make all

#### Fast Partial Previews Or Builds
## Fast Partial Previews Or Builds

In order to preview some changes faster (such as markup and CSS), you can disable all plugins and
languages except those you need by prefixing the `ENABLED_LANGS` and
Expand Down Expand Up @@ -168,7 +190,7 @@ run if the API site is running slow.

For a list of languages, look in the `_translations` directory.

#### Publishing Previews
## Publishing Previews

You can publish your previews online to any static hosting service.
[GitHub pages](https://pages.github.com/) is a free service available to
Expand Down
14 changes: 7 additions & 7 deletions docs/working-with-github.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
## Working With GitHub
# Working With GitHub

GitHub allows you to make changes to a project using git, and later submit them
in a "pull request" so they can be reviewed and discussed. In order to use
Expand All @@ -8,13 +8,13 @@ git](https://help.github.com/articles/set-up-git). You will also need to
from its [GitHub page](https://github.com/bitcoin-dot-org/bitcoin.org) and clone
your GitHub repository into a local directory with the following command lines:

```
```bash
git clone (url provided by GitHub on your fork's page) bitcoin.org
cd bitcoin.org
git remote add upstream https://github.com/bitcoin-dot-org/bitcoin.org.git
```

**How to send a pull request**
## How to send a pull request

1. Checkout to your master branch. `git checkout master`
2. Create a new branch from the master branch. `git checkout -b (any name)`
Expand All @@ -30,7 +30,7 @@ When submitting a pull request, please take required time to discuss your
changes and adapt your work. It is generally a good practice to split unrelated
changes into separate branches and pull requests.

**Travis Continuous Integration (CI)**
## Travis Continuous Integration (CI)

Shortly after your Pull Request (PR) is submitted, a Travis CI job will
be added to [our queue](https://travis-ci.org/bitcoin-dot-org/bitcoin.org). This
Expand Down Expand Up @@ -59,21 +59,21 @@ builds before opening a pull request, it's really simple:
name when the build finishes, and clicking on the icon will take you
to the corresponding build report.

**How to make additional changes in a pull request**
## How to make additional changes in a pull request

You simply need to push additional commits on the appropriate branch of your
GitHub repository. That's basically the same steps as above, except you don't
need to re-create the branch and the pull request.

**How to reset and update your master branch with latest upstream changes**
## How to reset and update your master branch with latest upstream changes

1. Fetch upstream changes. `git fetch upstream`
2. Checkout to your master branch. `git checkout master`
3. Replace your master branch by the upstream master branch. `git reset --hard
upstream/master`
4. Replace your master branch on GitHub. `git push origin master -f`

**Advanced GitHub Workflow**
## Advanced GitHub Workflow

If you continue to contribute to Bitcoin.org beyond a single pull
request, you may want to use a more [advanced GitHub
Expand Down