¶ Install Git on your computer
- Go to https://git-scm.com/.
- Download installer for your operative system. You have a full tutorial on how to install in different OS here: Installing Git. On Windows use the installer and leave all default options.
- Check that Git is correctly installed executing this in a terminal:
git --version. If the version number is returned then Git is OK. - Execute next commands in a terminal (Git installs a terminal called Git CMD that you can use) to set up your identity in Git, with your name and email. This is needed in order to Git to set you as contributor to the code.
git config --global user.name "John Doe"
git config --global user.email johndoe@example.com
¶ Create a GitHub account
You need a GitHub account.
- Go to https://github.com
- If you already have an account, click Sign in and validate.
- If you don’t have an account, create one by clicking Sign up. Enter a username, an email address, and a password. Once you have an account, log into GitHub with it.
- The first time you enter GitHub, it will ask you to do a verification through our email account. Once verified, you will appear on the GitHub home page.
¶ Install Node.js on your computer
Node.js is a requirement to make Urantiapedia Tools work.
- Go to https://nodejs.org/.
- Download Node.js. Use the current LTS version available.
- Install with default options.
- Check that Node.js is correctly installed. Open a terminal and execute
node -v. If the version number appears then Node.js is OK.
¶ Fork Urantiapedia project
- Open Urantiapedia project pages:
- Create a fork of each project. A fork is nothing but a proper copy of an existing project in our account, so that the changes made to this project do not affect the original project. To make the forks click on the Fork button in the upper right corner of each GitHub page.
- In a few seconds a copy of Urantiapedia projects will be created within your GitHub account. These projects are a fresh copy in which you can make the changes you need, without affecting the original projects.
¶ Install VS Code and GitLens
It is recommended the use of Visual Studio Code.
- Go to https://code.visualstudio.com/.
- Download and install it. During installation it is recommended to check the “Add action ‘Open with Code’ to folder context menu” if you are a Windows user.
- Open it. First time it is opened you can set up some settings. Skip them all.
- In VS Code click in Extensions button on the left side buttonbar. It is highly recommended to install an extension called “GitLens”. It is usually among the most popular extensions. Locate it and click in install button.
- Now you will have a new button for GitLens in VS Code left buttonbar. Click on it and click in “Welcome (Quick setup)” button. The Welcome page opens. It is recommended to select “Source control layout” as the default view. This makes GitLens to merge with the default “Source control” panel in VS Code.
¶ Clone Urantiapedia projects
- Open GitHub web and go to your account.
- Open your forks of Urantiapedia projects you created before.
- On the main page locate a green menu named “Code” and in it click to copy the URL of the project, something like
https://github.com/<username>/urantiapedia.gitandhttps://github.com/<username>/urantiapedia-backup.git. - Open VS Code, open “Source control” panel and click in “Clone repository”.
- In the textbox that appears type or paste the previous path copied.
- Select “Clone from GitHub”.
- Allow in the GitHub extension to sign in.
- A web page appears asking to authorize VS Code to access GitHub. Click Continue.
- Click in Authorize github.
- Now you are redirected to a new webpage and a message opens. Click in “Open VS Code”.
- Now click Open to allow the use of the URI path provided. If something goes wrong repeat from point 4.
- When the name of your Urantiapedia repository is shown in the command palette select it. A dialog appears asking for a folder. Select any folder for the project or create one.
- Wait some seconds for VS Code to clone the repo. Finally click in “Open repo”. Also click in “Yes, I trust the authors”.
- The project will be opened correctly.
¶ Set up Urantiapedia Tools
Urantiapedia Tools is a JavaScript desktop app developed with Electron. To install and execute it follow these steps:
- Open VS Code and select File > Open folder. Then select the root folder of the project, the one that contains the
package.jsonfile. - Alternatively, in Windows you can open the context menu of the root folder and select “Open with Code”.
- Open a terminal using Terminal > New Terminal. Ensure that terminal is opened in root folder of the project.
- To install dependencies execute:
npm install. Wait until all of them are installed. - The project is set up with a default launch configuration. Press F5 to execute or in the terminal execute
npm run start. - The application opens. By default a Dev Tools window is opened for debugging. You can ignore it or close it if not developing.
¶ Commit and push changes
Your local repositories are a full copy of the projects so you can save changes in them each time you have some changes that can be posted.
- You will see that you have changes when a number appears in the “Source control” button icon.
- Click in “Source control”.
- On the “Source control” subpanel you will see a list of changed files. Hover the mouse over them and click on the button “Stage changes” that will appear.
- Once changes are in the stage, enter a message for the commit and click in “Commit” button. The changes are added to your local repo.
- To send your changes to your remote repository in GitHub click in the “Sync changes” button that appears when new commits exists. This will pull and push any changes between your local and remote copies of the project.
- You can check that your commits are pushed correctly opening your GitHub Urantiapedia page.
¶ Synchronize changes between projects
The Urantiapedia project is the version for development and work with the contents. The Urantiapedia-backup project contains only the content, and is in sync with the web page, so making changes to it is equivalent to making massive changes to the web.
If your changes to the Urantiapedia project include changes to the content (/output/wikijs folder) you must sync those changes to the Urantiapedia-backup project with any sync utility or by simply copying and pasting between folders.
¶ Create “pull requests” to Urantiapedia projects
When you have an enough number of commits pushed to your own forks of the Urantiapedia projects, you can send your changes to the projects so that changes can be reviewed and merged in it. This is called a “pull request” in GitHub terminology.
- Open each of Urantiapedia pages in GitHub.
https://github.com/<username>/urantiapediahttps://github.com/<username>/urantiapedia-backup
- Ensure your are in the main branch that is called “master”. The branch appears in a menu on top of the list of files.
- Select the menu Contribute that appears below, and then select “Open pull request”. If the menu says “This branch is not ahead of the upstream master” you must do first a fetch of the main project. See below.
- Add a title to your contributions. You can also add a description.
- Click on “Create pull request”. Do a “pull request” for each project with changes.
- This will send a notification to “admin” users of the project that will merge your changes if they find no problems.
¶ Sync your forks
As Urantiapedia is the effort of a team of collaborators, it is common that at any point in time your forks of projects will be out of sync with the main projects. It is a good practice that before any pull request you sync your forks with the main projects.
- Open any of your Urantiapedia pages in GitHub.
- Select the menu “Fetch upstream” that appears below the branch selector and click in “Fetch and merge”. This will copy all new changes from main project to your fork project.
- Go to VS Code.
- Open the project and previously explained.
- In “Source control” panel go to “Remotes” subpanel. You must have a remote repositiry listed there called
JanHerca/urantiapedia. Click in the “Fetch” button next to the name. This action does a fetch and a push at the same time to sync the local repository. - Sometimes changes in “Urantiapedia Tools” code imply changes to dependencies. You must install or update new dependencies executing the command
npm installfrom a terminal in VS Code. This will update dependencies for the project.
¶ Summary
In summary, the process in GitHub is as follows (see the diagram):
- “Editor-in-Chief” creates a fork (a copy in its own account) of Urantiapedia projects on GitHub: Urantiapedia and Urantiapedia-backup.
- “Editor-in-Chief” creates a local copy of the projects on PC. This is done first through a clone action and later through fetch upstream actions in GitHub web and through pulls actions to the local projects, that downloads any change to the local copy.
- “Editor-in-Chief” makes changes in the local copy of the projects and makes commmits to the local copy.
- “Editor-in-Chief” send changes to the GitHub projects through push actions.
- Then “Editor-in-Chief” creates pull requests from the GitHub website for both projects: Urantiapedia and Urantiapedia-backup.
- This pull requests of “Editors-in-Chief” are reviewed by “Administrators”, who are in charge of doing a merge with the main branch (master) of all those changes that are correct. Any changes that are not correct will be rejected and “Editors-in-Chief” will be notified to fix them.
- When changes are OK an “Administrator” do a merge of them and they are synchronized automatically to the web.
¶ External links
- Urantiapedia Tools - GitHub project
- Urantiapedia-backup - GitHub project
- Urantia Foundation
- Blue Fields
- Wiki.js