From 4eff7d5d450c4acdef3249c5d588275c77e4e336 Mon Sep 17 00:00:00 2001 From: Robert Krátký Date: Dec 03 2017 17:59:17 +0000 Subject: Use HTML mark-up to work around Pagure's borked MD rendering. --- diff --git a/README.md b/README.md index c4cd0d7..2a74a90 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Please report Issues and submit Pull Requests for **Publishing Fixes** here. Co ## Testing your changes locally -To test your changes, first install `asciibinder` +To test your changes, first install asciibinder ``` $ sudo dnf install ruby-devel @@ -34,133 +34,117 @@ Publishing uses two repos: ### Pre-requisities -1. You need `git` and `asciibinder`. - - ``` - $ gem install ascii_binder - $ sudo dnf install git - ``` - -2. You need both repositories - - ``` - $ git clone ssh://git@pagure.io/fedora-docs/docs-fp-o.git - $ git clone ssh://git@pagure.io/fedora-docs/fedora-docs-web.git - ``` +
    +
  1. You need git and asciibinder. + 
    +$ gem install ascii_binder
+$ sudo dnf install git
    +
    2. +
  2. You need both repositories + 
    +$ git clone ssh://git@pagure.io/fedora-docs/docs-fp-o.git
+$ git clone ssh://git@pagure.io/fedora-docs/fedora-docs-web.git
    +
    3. +
### Publishing -1. Go to the `docs-fp-o` repository and ensure you are on master and that it is up-to-date - - ``` - $ cd - $ git checkout master - $ git pull - ``` - -2. Prepare the repo to be built by loading in all documentation sources. - - ``` - $ ./builder.sh - ``` - - This will generate a whole lot of output. - -3. Build the site - - ``` - $ asciibinder package - ``` - - This will also generate a lot of output. - -4. Stage the site - - ``` - $ cp -r _package/main/* - $ cd - $ git checkout stg - $ git add . - $ git commit -m "Updating site" - $ git push - ``` - -5. Review the staged site at [docs.stg.fedoraproject.org](https://docs.stg.fedoraproject.org) and see if it looks good. The site is updated approximately every 5 minutes, so give it time. - -6. If you're happy, push the changes to production. - - ``` - $ git checkout prod - $ git merge stg - $ git push - ``` - -7. Verify your changes have gone live at [docs.fedoraproject.org](https://docs.fedoraproject.org) and see if they look good. The production site is refreshed once per hour so this may take some time. +
    +
  1. Go to the docs-fp-o repository and ensure you are on master and that it is up-to-date + 
    +$ cd 
+$ git checkout master
+$ git pull
    +
    2. +
  2. Prepare the repo to be built by loading in all documentation sources. + 
    +$ ./builder.sh
    +

    This will generate a whole lot of output.

    +
    3. +
  3. Build the site + 
    +$ asciibinder package
    +

    This will also generate a lot of output.

    +
    4. +
  4. Stage the site + 
    +$ cp -r _package/main/* 
+$ cd 
+$ git checkout stg
+$ git add .
+$ git commit -m "Updating site"
+$ git push
    +
    5. +

  5. Review the staged site at docs.stg.fedoraproject.org and see if it looks good. The site is updated approximately every 5 minutes, so give it time.

    6. +
  6. If you're happy, push the changes to production. + 
    +$ git checkout prod
+$ git merge stg
+$ git push
    +
    7. +
  7. Verify your changes have gone live at docs.fedoraproject.org and see if they look good. The production site is refreshed once per hour so this may take some time.
    8. +
### Branching New Releaess In each content repository (i.e. https://pagure.io/fedora-docs/install-guide): -1. Go to the master branch - ```` - $ git checkout master - ```` - -2. Branch for the new release, Fedora 27 in this example: - ```` - $ git checkout -b f27 - ```` - -3. Update the entities file to reflect the correct version numbers - ```` - $ vi en-US/entities.adoc - ```` - -4. Commit your changes and push to the upstream repository - ```` - $ git add en-US/entities.adoc - $ git commit -m "Branching for F27" - $ git push upstream f27 - ```` - -5. Return to the master branch - ```` - $ git checkout master - ```` - -6. Update the _distro_map.yml file to add the new version - ```` - $ vi _distro_map.yml - ```` - -7. Commit your changes and push to the upstream repository - ```` - $ git add _distro_map.yml - $ git commit -m "Branching for F27 - updating _distro_map.yml" - $ git push upstream master - ```` +
    +
  1. Go to the master branch + 
    +$ git checkout master
    +
    2. +
  2. Branch for the new release, Fedora 27 in this example: + 
    +$ git checkout -b f27
    +
    3. +
  3. Update the entities file to reflect the correct version numbers + 
    +$ vi en-US/entities.adoc
    +
    4. +
  4. Commit your changes and push to the upstream repository + 
    +$ git add en-US/entities.adoc
+$ git commit -m "Branching for F27"
+$ git push upstream f27
    +
    5. +
  5. Return to the master branch + 
    +$ git checkout master
    +
    6. +
  6. Update the _distro_map.yml file to add the new version + 
    +$ vi _distro_map.yml
    +
    7. +
  7. Commit your changes and push to the upstream repository + 
    +$ git add _distro_map.yml
+$ git commit -m "Branching for F27 - updating _distro_map.yml"
+$ git push upstream master
    +
    8. +
In this repo, the builder repository: -Note: In the build directory the beta version is always in the `beta/` directory when published. +Note: In the build directory the beta version is always in the beta/ directory when published. -1. Edit the _distro_map.yml to reflect the addition of the new version. See the fXX-en-US lines: +1. Edit the _distro_map.yml to reflect the addition of the new version. See the fXX-en-US lines: -2. Edit builder.sh to add the new branch to the BRANCHES variable +2. Edit builder.sh to add the new branch to the BRANCHES variable -3. Edit build.sh to add a new variable to hold the list of content repositories for the new branch. See f26_BOOKS for an example. +3. Edit build.sh to add a new variable to hold the list of content repositories for the new branch. See f26_BOOKS for an example. -4. Edit the index-main.html to link to the new version, as needed. +4. Edit the index-main.html to link to the new version, as needed. ### Notes -The `asciibinder` command will incorrectly report that there are nonexistent topics in the `_topic_map.yml`. This is error is caused by ruby's Find module not following symlinks and is specific to this build repository. To validate a specific content set, test it with `asciibinder` in its source repository. +The asciibinder command will incorrectly report that there are nonexistent topics in the _topic_map.yml. This is error is caused by ruby's Find module not following symlinks and is specific to this build repository. To validate a specific content set, test it with asciibinder in its source repository. ## Project Plan Add new features - * remove `builder.sh` as new functionality arrives in `asciibinder` + * remove builder.sh as new functionality arrives in asciibinder * Translations * Search * CI/CD for automatic publishing and rebuild