joshua/dash-docs
1
0
Fork 0
mirror of https://github.com/seigler/dash-docs synced 2025-07-27 01:36:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Improve and promote instructions in the README

Browse source
This commit is contained in:
Saivann 2014-03-21 12:34:01 -04:00
parent 885b6b12b4
commit 92c6884702
2 changed files with 94 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

130
README.md
View file

@ -1,10 +1,49 @@
# Usage
## How to participate
**Easy preview**: Simple changes in the texts can be previewed live on bitcoin.org with any recent browser. 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.
You can report any problem or help to improve bitcoin.org by opening an issue or a [pull request](#working-with-github) on [GitHub](https://github.com/bitcoin/bitcoin.org). You can also help [translating bitcoin.org](#translation) on [Transifex](https://www.transifex.com/projects/p/bitcoinorg/).
**Real preview**: Install dependencies, edit the files, run jekyll (or "jekyll build" on older setups), and copy the output files from _site/ at the root of your web server. If you have no web server, run jekyll --server (or "jekyll serve" on older setups). This server requires you to add a trailing ".html" by hand in your browser window.
### Working with GitHub
## Requirements
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. Many online how-tos exist so you can learn git, [here's a good one](https://www.atlassian.com/git/tutorial/git-basics).
In order to use GitHub, you need to [sign up](http://github.com/signup) and [set up git](https://help.github.com/articles/set-up-git). You will also need to click the **Fork** button on the bitcoin.org [GitHub page](https://github.com/bitcoin/bitcoin.org) and clone your GitHub repository into a local directory using the following command lines:
```
git clone (url provided by GitHub on your fork's page) bitcoin.org
cd bitcoin.org
git remote add upstream https://github.com/bitcoin/bitcoin.org.git
```
**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)`
3. Edit files and [preview](#previewing) the result.
4. Track changes in files. `git add -A`
5. Commit your changes. `git commit -m '(short description for your change)'`
6. Push your branch on your GitHub repository. `git push origin (name of your branch)`
7. Click on your branch on GitHub and click the **Compare / pull request** button to send a pull request.
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 branchs and pull requests.
**How to make additional changes in a pull request**
You simply need to push additionnal 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**
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`
### Previewing
**Easy preview**: 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.
**Real preview**: Install [dependencies](#requirements), run jekyll (or "jekyll build" on older setups), and copy the output files from _site/ to the root of your web server. If you have no web server, run jekyll --server (or "jekyll serve" on older setups). This server requires you to add a trailing ".html" by hand in your browser address bar.
### Requirements
Installing dependencies on Ubuntu 12.10
@ -20,15 +59,18 @@ Installing dependencies on older Ubuntu and Debian distributions
### How to translate
* Translations can be done on Transifex https://www.transifex.com/projects/p/bitcoinorg/
You can join a translation team on [Transifex](https://www.transifex.com/projects/p/bitcoinorg/) and start translating or improving existing translations. Latest live previews and communications can be found on [this thread](https://bitcointalk.org/index.php?topic=349633.0).
* You must be a native speaker for the language you choose to translate.
* At least one other reviewer is required.
* Changing the meaning of any statement should be avoided. In doubt, you can open a discussion on Transifex.
* Sentences and popular expressions should be adapted so that they sound native in your language.
* Please be careful to preserve the original meaning of each text.
* Sentences and popular expressions should sound native in your language.
* Translations need to be reviewed by a reviewer or coordinator before publication.
* Once reviewed, translations can be [submitted](#import-translations) in a pull request on GitHub.
* **In doubt, please open a discussion on Transifex with coordinators. That'll be much appreciated.**
### Import translations
**Update translations**: You can update the relevant language file in \_translations/ and from the root of the git repository run ./\_contrib/updatetx.rb to update layouts and templates for this language. You should also make sure that no url has been changed by translators. If one page has been replaced or moved, a redirection can be added in \_config.yml.
**Update translations**: You can update the relevant language file in \_translations/ and from the root of the git repository run ./\_contrib/updatetx.rb to update layouts and templates for this language. You should also make sure that no url has been changed by translators. If any page needs to be moved, please add [redirections](#redirections).
**Add a new language**: You can put the language file from Transifex in \_translations and add the language in \_config.yml in the right display order for the language bar. Make sure to review all pages and check all links.
@ -54,7 +96,41 @@ Any change in the english texts can be done through a pull request on GitHub. If
(update en.yml)
tx push -s -t -f --skip --no-interactive
## Advanced Usage
## Posts
### Events
Events should be placed in `_events/YYYY-MM-DD-SHORTTITLE.md` and adhere to this format:
```
---
title: "2014 Texas Bitcoin Conference"
venue: "Circuit of the Americas™ - Technology and Conference Center"
address: "9201 Circuit of the Americas Blvd"
city: "Austin, TX"
country: "United States"
link: "http://texasbitcoinconference.com/"
---
```
### Release Notes
Release notes should be placed in `_releases/YYYY-MM-DD-VERSION.md` and adhere to this format:
```
---
title: Bitcoin Core version 0.9.0 released
src: http://sourceforge.net/p/bitcoin/mailman/message/32119564/
---
Bitcoin Core v0.9.0 is now available for download at
<https://bitcoin.org/bin/0.9.0/>
...
```
* `VERSION` is used to define the version and construct the URL. It should adhere to this format: `v0.3.24`.
* `title: ...` will be used as the title
* `src: ...` (optional) link to full annoucement
### Alerts
@ -86,38 +162,14 @@ More information will follow.
* `banner: ...` (optional) a short text that will be displayed in a red alert banner and link to the alert page.
* `last updated: ...` should be kept up to date and be in RFC 2822 format ( date -uR ).
### Release Notes
## Advanced Usage
Release notes should be placed in `_releases/YYYY-MM-DD-VERSION.md` and adhere to this format:
### Redirections
Redirections can be defined in ```_config.yml```.
```
---
title: Bitcoin Core version 0.9.0 released
src: http://sourceforge.net/p/bitcoin/mailman/message/32119564/
---
Bitcoin Core v0.9.0 is now available for download at
<https://bitcoin.org/bin/0.9.0/>
...
```
* `VERSION` is used to define the version and construct the URL. It should adhere to this format: `v0.3.24`.
* `title: ...` will be used as the title
* `src: ...` (optional) link to full annoucement
### Events
Events should be placed in `_events/YYYY-MM-DD-SHORTTITLE.md` and adhere to this format:
```
---
title: "2014 Texas Bitcoin Conference"
venue: "Circuit of the Americas™ - Technology and Conference Center"
address: "9201 Circuit of the Americas Blvd"
city: "Austin, TX"
country: "United States"
link: "http://texasbitcoinconference.com/"
---
/news: /en/version-history
```
### Aliases for contributors