Actions

Difference between revisions of "Developer Area/Mahara manual setup"

From Mahara Wiki

< Developer Area
(Created page with "=Introduction= The [http://manual.mahara.org Mahara user manual] uses a number of tools to generate the end product. The [http://www.slideshare.net/4nitsirk/catalyst-pizza-thurs…")
 
(17 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
The [http://manual.mahara.org Mahara user manual] uses a number of tools to generate the end product. The [http://www.slideshare.net/4nitsirk/catalyst-pizza-thursdaytalkmaharamanual20120607 presentation by Kristina Hoeppner] illustrates the process and tools used briefly.
 
The [http://manual.mahara.org Mahara user manual] uses a number of tools to generate the end product. The [http://www.slideshare.net/4nitsirk/catalyst-pizza-thursdaytalkmaharamanual20120607 presentation by Kristina Hoeppner] illustrates the process and tools used briefly.
  
The following are notes for setting up a new branch for the user manual. It requires that Sphinx is already installed. The example below uses Mahara version 1.9 as an example. Any reference to 1.9 would need to be replaced with the version that you are creating the manual branch for.
+
The following are notes for setting up a new branch for the user manual which is generally done by Catalyst. It requires that Sphinx is already installed. The example below uses Mahara version 15.10 as an example. Any reference to it would need to be replaced with the version that you are creating the manual branch for.
 +
 
 +
=Set up Python locally=
 +
 
 +
A Python developer recommended to set up a virtual environment instead of installing Sphinx directly as root.
 +
 
 +
Set up the folder for the user manual.
 +
 
 +
  cd code
 +
  mkdir manual1510
 +
 
 +
Please follow the [http://docs.python-guide.org/en/latest/dev/virtualenvs/ instructions] for setting up, activating and deactivating a virtual environment. It should be installed in this folder under the default "venv" folder (will be created as part of the setup). That folder is then part of gitignore and will not be committed back to the project. If you call your folder differently, you need to update .gitignore.
  
 
=Setting up a new local and remote branch=
 
=Setting up a new local and remote branch=
Line 9: Line 20:
 
1. Do a checkout of the code in the new folder for the manual:
 
1. Do a checkout of the code in the new folder for the manual:
  
 +
via SSH:
 +
  cd code
 +
  git clone [email protected]:user-manual/manual.git manual1510
 +
 +
via HTTPS:
 
   cd code
 
   cd code
   git clone git://gitorious.org/mahara/mahara.git manual19
+
   git clone https://git.mahara.org/user-manual/manual.git manual1510
  
 
2. Create a new local branch for the new version of the manual
 
2. Create a new local branch for the new version of the manual
  
 
   git branch
 
   git branch
   git checkout -b 1.9_STABLE
+
   git checkout -b 15.10_STABLE
  
 
3. Replace the information in .git/config with the following.
 
3. Replace the information in .git/config with the following.
  
 
   [core]
 
   [core]
    repositoryformatversion = 0
+
    repositoryformatversion = 0
    filemode = true
+
    filemode = true
    bare = false
+
    bare = false
    logallrefupdates = true
+
    logallrefupdates = true
  [remote "origin"]
+
  [remote "origin"]
    fetch = +refs/heads/*:refs/remotes/origin/*
+
    fetch = +refs/heads/*:refs/remotes/origin/*
    url = git@gitorious.org:mahara/manual.git
+
    url = git@git.mahara.org:user-manual/manual.git
  [branch "1.9_STABLE"]
+
  [branch "15.10_STABLE"]
    remote = origin
+
    remote = origin
    merge = refs/heads/1.9_STABLE
+
    merge = refs/heads/15.10_STABLE
 +
 
 +
 
 +
4. Publish the new branch on git.mahara.org
  
4. Publish the new branch on Gitorious
+
  git push origin 15.10_STABLE:refs/heads/15.10_STABLE
  
  git push origin 1.9_STABLE:refs/heads/1.9_STABLE
+
5. Make initial changes to index.php, manual-build/config.py.
  
5. Make initial changes to index.php, config.py, mahara/links.html to reflect that you are now dealing with a new version of the manual. Commit the changes and push them to Gitorious.
+
=Include in build process=
  
 +
'''Catalyst only'''
 +
 +
# Build the new version and publish it by Gitlab.
 +
## Create a new schedule in the CI/CD process.
 +
## Description: Version (Daily)
 +
## Variables: “MAHARA_VERSION” and enter the version number in the field to the right.
 +
## Interval patterns: Select “Every day” first and then switch to “Custom” and change the cron time. Note: Do not schedule all builds at the same time but spread things out a bit.
 +
# Run the build manually. Note: To see which version of the manual was run, go to Pipelines -> Click the Status icon and then on the next screen click the “Passed” icon and see the console output.
 +
# Once ready to have the manual publicly linked: Add the new release to conf-common.py for “mahara_releases” and “all_mahara_releases”. Remove the version that is fallen / has fallen out of support from "mahara_releases".
 +
# Re-assess the auto build frequency of older releases.
 +
# When the new version of Mahara has been released, go to manual-build/source/index.html and change the version number on line 22, i.e. window.location = "https://manual.mahara.org/" + lang + "/18.10/";
  
 
=Setting up the translation export branch for Launchpad=
 
=Setting up the translation export branch for Launchpad=
 +
 +
'''This is done by Catalyst'''
  
 
This part is the tricky bit as Launchpad uses bzr for version control. There is a [http://doc.bazaar.canonical.com/latest/en/mini-tutorial/ good tutorial on how to work with bzr] that can help anyone get started.
 
This part is the tricky bit as Launchpad uses bzr for version control. There is a [http://doc.bazaar.canonical.com/latest/en/mini-tutorial/ good tutorial on how to work with bzr] that can help anyone get started.
Line 46: Line 78:
 
1. Assumption: Folder code/manual-export/manual-export exists.
 
1. Assumption: Folder code/manual-export/manual-export exists.
  
2. Create the new folder "1.9_STABLE-export".
+
2. Create the new folder "15.10_STABLE-export".
  
 
3. Generate the potfiles in your manual folder.
 
3. Generate the potfiles in your manual folder.
  
   cd code/manual19
+
   cd code/manual1510
 
   sphinx-build -b gettext source potfiles
 
   sphinx-build -b gettext source potfiles
  
4. Go back to the export folder. If the potfiles generation doesn't produce folders in which the potfiles are listed (sometimes it does, sometimes it doesn't), create a folder for each potfile. The folder name needs to match the potfile name (minus the extension). The folders will be empty and don't have the actual potfiles in them. Your folder 1.9_STABLE-export should contain the sub folder "potfiles" and in there a folder for each potfile that has the name of the potfile, but the potfile is not in it.
+
4. Go back to the export folder. If the potfiles generation doesn't produce folders in which the potfiles are listed (sometimes it does, sometimes it doesn't), create a folder for each potfile. The folder name needs to match the potfile name (minus the extension). The folders will be empty and don't have the actual potfiles in them. Your folder 15.10_STABLE-export should contain the sub folder "potfiles" and in there a folder for each potfile that has the name of the potfile, but the potfile is not in it.
  
 
5. Create the bzr files
 
5. Create the bzr files
  
 
   cd manual-export
 
   cd manual-export
   bzr init manual-export/1.9_STABLE-export/
+
   bzr init manual-export/15.10_STABLE-export/
  
 
6. Enter your potfiles export folder and commit the folders.
 
6. Enter your potfiles export folder and commit the folders.
  
   cd manual-export/1.9_STABLE-export/
+
   cd manual-export/15.10_STABLE-export/
 
   bzr add potfiles/
 
   bzr add potfiles/
 
   bzr commit
 
   bzr commit
Line 69: Line 101:
 
7. Push your newly created branch to Launchpad
 
7. Push your newly created branch to Launchpad
  
   bzr push lp:~mahara-lang/mahara-manual/1.9_STABLE-export
+
   bzr push lp:~mahara-lang/mahara-manual/15.10_STABLE-export
  
8. Go to Launchpad and set up the export branch for your translation: https://translations.launchpad.net/mahara-manual/1.9/+translations-settings
+
8. Go to Launchpad and set up the export branch for your translation: https://translations.launchpad.net/mahara-manual/15.10/+translations-settings
  
 
   Under "Exporting translations to branch" click the "Edit" button. Then type into the field / search for the branch:
 
   Under "Exporting translations to branch" click the "Edit" button. Then type into the field / search for the branch:
   ~mahara-lang/mahara-manual/1.9_STABLE-export
+
   ~mahara-lang/mahara-manual/15.10_STABLE-export
 
   confirm the branch
 
   confirm the branch
  
 
9. Upload the potfiles into the import branch. Make sure that you set the path to "potfiles/[name of the potfile folder]/[potfile]
 
9. Upload the potfiles into the import branch. Make sure that you set the path to "potfiles/[name of the potfile folder]/[potfile]

Revision as of 17:52, 6 October 2019

Introduction

The Mahara user manual uses a number of tools to generate the end product. The presentation by Kristina Hoeppner illustrates the process and tools used briefly.

The following are notes for setting up a new branch for the user manual which is generally done by Catalyst. It requires that Sphinx is already installed. The example below uses Mahara version 15.10 as an example. Any reference to it would need to be replaced with the version that you are creating the manual branch for.

Set up Python locally

A Python developer recommended to set up a virtual environment instead of installing Sphinx directly as root.

Set up the folder for the user manual.

 cd code
 mkdir manual1510

Please follow the instructions for setting up, activating and deactivating a virtual environment. It should be installed in this folder under the default "venv" folder (will be created as part of the setup). That folder is then part of gitignore and will not be committed back to the project. If you call your folder differently, you need to update .gitignore.

Setting up a new local and remote branch

1. Do a checkout of the code in the new folder for the manual:

via SSH:

 cd code
 git clone [email protected]:user-manual/manual.git manual1510

via HTTPS:

 cd code
 git clone https://git.mahara.org/user-manual/manual.git manual1510

2. Create a new local branch for the new version of the manual

 git branch
 git checkout -b 15.10_STABLE

3. Replace the information in .git/config with the following.

 [core]
    repositoryformatversion = 0
    filemode = true
    bare = false
    logallrefupdates = true
  [remote "origin"]
    fetch = +refs/heads/*:refs/remotes/origin/*
    url = [email protected]:user-manual/manual.git
  [branch "15.10_STABLE"]
    remote = origin
    merge = refs/heads/15.10_STABLE


4. Publish the new branch on git.mahara.org

 git push origin 15.10_STABLE:refs/heads/15.10_STABLE 

5. Make initial changes to index.php, manual-build/config.py.

Include in build process

Catalyst only

  1. Build the new version and publish it by Gitlab.
    1. Create a new schedule in the CI/CD process.
    2. Description: Version (Daily)
    3. Variables: “MAHARA_VERSION” and enter the version number in the field to the right.
    4. Interval patterns: Select “Every day” first and then switch to “Custom” and change the cron time. Note: Do not schedule all builds at the same time but spread things out a bit.
  2. Run the build manually. Note: To see which version of the manual was run, go to Pipelines -> Click the Status icon and then on the next screen click the “Passed” icon and see the console output.
  3. Once ready to have the manual publicly linked: Add the new release to conf-common.py for “mahara_releases” and “all_mahara_releases”. Remove the version that is fallen / has fallen out of support from "mahara_releases".
  4. Re-assess the auto build frequency of older releases.
  5. When the new version of Mahara has been released, go to manual-build/source/index.html and change the version number on line 22, i.e. window.location = "https://manual.mahara.org/" + lang + "/18.10/";

Setting up the translation export branch for Launchpad

This is done by Catalyst

This part is the tricky bit as Launchpad uses bzr for version control. There is a good tutorial on how to work with bzr that can help anyone get started.

The following steps are a bit incomplete, but will hopefully fleshed out in the future.

1. Assumption: Folder code/manual-export/manual-export exists.

2. Create the new folder "15.10_STABLE-export".

3. Generate the potfiles in your manual folder.

 cd code/manual1510
 sphinx-build -b gettext source potfiles

4. Go back to the export folder. If the potfiles generation doesn't produce folders in which the potfiles are listed (sometimes it does, sometimes it doesn't), create a folder for each potfile. The folder name needs to match the potfile name (minus the extension). The folders will be empty and don't have the actual potfiles in them. Your folder 15.10_STABLE-export should contain the sub folder "potfiles" and in there a folder for each potfile that has the name of the potfile, but the potfile is not in it.

5. Create the bzr files

 cd manual-export
 bzr init manual-export/15.10_STABLE-export/

6. Enter your potfiles export folder and commit the folders.

 cd manual-export/15.10_STABLE-export/
 bzr add potfiles/
 bzr commit
 write commit message

7. Push your newly created branch to Launchpad

 bzr push lp:~mahara-lang/mahara-manual/15.10_STABLE-export

8. Go to Launchpad and set up the export branch for your translation: https://translations.launchpad.net/mahara-manual/15.10/+translations-settings

 Under "Exporting translations to branch" click the "Edit" button. Then type into the field / search for the branch:
 ~mahara-lang/mahara-manual/15.10_STABLE-export
 confirm the branch

9. Upload the potfiles into the import branch. Make sure that you set the path to "potfiles/[name of the potfile folder]/[potfile]