Search Unity

Editor for GitHub Wiki

Discussion in 'Open Projects' started by DSivtsov, Dec 9, 2020.

  1. DSivtsov

    DSivtsov

    Joined:
    Feb 20, 2019
    Posts:
    151
    If you decided to participate in creation of Wiki for Open Project, but you isn't part of collaboration team of this Project yet (not included in Contributions list of project yet). You can create/edit md files (and corresponding pictures) and sent it to "project integrators" by Pull requests.

    But GitHub haven't standard standalone tools for creation and testing these Wiki changes (standard variant - use online tools by contributions).
    Below a procedure which can give to you possibility to create and testing these Wiki changes before creating PR:

    1. On Web GUI GitHub (in your github account)
    - Create a new repository, by example - OpenProjectOriginWiki (full name will be <Your GitHub Account>/OpenProjectOriginWiki)
    I recommend add some Readme.md at creation or latter:
    - git add Readme.md
    - git commit -m "Create README.md"

    2. On Web GUI GitHub create Wiki for your project OpenProjectOriginWiki, it's mandatory (!!!).
    - Create first page (by default Home)
    Note. On Page below you can find link to clone repository (it's fully separated from main repo where exist the Readme.md)

    3. Clone this wiki locally, in my example, it will be - https://github.com/<Your GitHub Account>/OpenProjectOriginWiki.wiki.git

    Note. All next command I do in Git Terminal, which can be simple run from every Git GUI (GitHub Desktop, or SourceTree or other). If you run from right repo, it will run in right environment (right current directory and other parameters).

    4. in Git Terminal create link to remote Open Project Wiki
    - Check current remote parameters (you must see the same output)
    $ git remote -v
    origin https://github.com/DSivtsov/OpenProjectOriginWiki.wiki.git (fetch)
    origin https://github.com/DSivtsov/OpenProjectOriginWiki.wiki.git (push)

    - Add remote repo from OpenProject Wiki (link also can be copied from any page of
    OpenProject Wiki)
    $ git remote add upstream https://github.com/UnityTechnologies/open-project-1.wiki.git

    - After this you must have the same
    $ git remote -v
    origin https://github.com/DSivtsov/OpenProjectOriginWiki.wiki.git (fetch)
    origin https://github.com/DSivtsov/OpenProjectOriginWiki.wiki.git (push)
    upstream https://github.com/UnityTechnologies/open-project-1.wiki.git (fetch)
    upstream https://github.com/UnityTechnologies/open-project-1.wiki.git (push)

    5. in Git Terminal update local branch from remote Open Project Wiki
    - Get current state of OpenProject Wiki (message error in the end, It's normal)
    $ git pull upstream master
    ...
    From https://github.com/UnityTechnologies/open-project-1.wiki
    * branch master -> FETCH_HEAD
    * [new branch] master -> upstream/master
    fatal: refusing to merge unrelated histories

    - You rebase your local master branch on branch from OpenProject Wiki (upstream/master)
    $ git rebase upstream/master
    error: could not apply 23156bc... Initial Home page
    Resolve all conflicts manually, mark them as resolved with
    "git add/rm <conflicted_files>", then run "git rebase --continue".
    You can instead skip this commit: run "git rebase --skip".
    To abort and get back to the state before "git rebase", run "git rebase --abort".
    Could not apply 23156bc... Initial Home page
    CONFLICT (add/add): Merge conflict in Home.md
    Auto-merging Home.md

    - After this you must by any simple editor (Notepad / Notepad ++) edit Home.md in directory where you place your local copy of repo. You must leave the Home.md in state as it exist in OpenProject Wiki and remove the all you put, when you create the "first page" (Step 2) and lines with GitHub conflict markers (<<< / === / >>>) see more info in Resolving a merge conflict using the command line and
    Understanding Git conflict markers

    - After this you must Update Home.md "include in process of rebase" and continue rebase
    $ git add .
    $ git rebase --continue

    - After this you will have in local directory the current state of OpenProject Wiki

    6. Replace the content of your Wiki (OpenProjectOriginWiki) by OpenProject Wiki
    $ git push origin -f
    ...
    To https://github.com/DSivtsov/OpenProjectOriginWiki.wiki.git
    + 23156bc...000f73b master -> master (forced update)

    - After this you can access the copy of OpenProject Wiki through your Wiki by standard GitHub Tools
    https://github.com/<Your GitHub Account>/OpenProjectOriginWiki/wiki

    Note. If you didn't change anything the all link will direct to original pages of OpenProject Wiki
    The "standard format link" to Pages
    https://github.com/UnityTechnologies/open-project-1/wiki/<Page Name>
    The "standard format link" to Pictures
    https://raw.githubusercontent.com/UnityTechnologies/open-project-1/main/Docs/WikiImages/<Picture Name>

    !!!Except the pages which will have linked to "your Wiki page"
    https://github.com/DSivtsov/OpenProjectOriginWiki/wiki, but contain data of OpenProject Wiki
    https://github.com/DSivtsov/OpenProjectOriginWiki/wiki/_Sidebar
    https://github.com/DSivtsov/OpenProjectOriginWiki/wiki/_Footer
    (vs DSivtsov will be <Your GitHub Account>)

    7. What We receive After this:
    - You can you use the online GitHub tools edit your Wiki (OpenProject Wiki) - add new pages and connect it to "_Sidebar". All new page will stored in your Wiki on GitHub (format "your Wiki page").
    If it demands you must put your picture in corresponding local folder ("open-project-1\Docs\WikiImages" from your copy of main Repo Project).

    - If you want update the existen Wiki pages (may be you decided make some correction), You must at beginning replace corresponding link in "_Sidebar" onto the corresponding page from your Wiki (use format "your Wiki page"):
    replace "UnityTechnologies/open-project-1" on "DSivtsov/OpenProjectOriginWiki"
    (don't forget, if it also demands, also change link for pictures on page).

    8.Additionally I recommend to create separate branch for your customization Wiki
    It give possibilities to separated your changes from regular updates of OpenProject Wiki (you can receive updates and continue you customization)
    - in Git Terminal (current branch master)
    - Create new branch based on current branch and switch on it
    $ git checkout -b UpdateWiki
    Switched to a new branch 'UpdateWiki'

    - Get current state from your Wiki (origin/master) To new branch (UpdateWiki). After this on local will be files synced with current state of your Wiki (You can replace link to "standard format link" in updated/new pages and make PR, don't forget about your pictures and links to it)
    $ git pull origin master:UpdateWiki
    From https://github.com/DSivtsov/OpenProjectOriginWiki.wiki
    000f73b..2f32e23 master -> UpdateWiki
    ....
    Note. All changes to Wiki by online GitHub tools followed by automatic commit.
    All editor page at bottom have the field Comments, which will use as comment for corresponding commit.

    9. receive Updates from OpenProject Wiki,
    - Switch on master branch
    $get checkout master
    - And after this see Step 5. You may have some conflict if you changed some files in local branch master (if you didn't create the separate branch).
    NOTE!!! Don't forget your online Wiki = origin/master - you can have only one branch - master, which will show as Wiki and support GitHub tools. On local you can have as many branch as you want. And when you want update content of online Wiki, you must decided, which content you will use:

    - if you want content from master:

    $ get checkout master
    $ git push origin -f

    - if you want content from UpdateWiki:

    $ git push origin UpdateWiki:master

     
    Last edited: Dec 10, 2020