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.
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.
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.
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.git and https://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”.
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.
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.
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.
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.
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 install from a terminal in VS Code. This will update dependencies for the project.
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.