openedx-atlas
#############
An Open edX CLI tool for moving translation files from openedx-translations.
Overview
--------
OEP-58 proposes changes to the way the Open edX Organization organizes and maintains
translation files. Atlas is an Open edX CLI tool that uses git's sparse-checkout to
download directories with the repository openedx-translations. These directories
correspond to repositories within the GitHub openedx organization. They contain
translation files downloaded from Transifex that have been translated by the Open edX
Translations Working Group.
Atlas is intended for both development and deployment, and is meant to be used after
cloning a repository with translation files kept in openedx-translations. For instance,
when building a docker image or testing localization strings locally. It should not be
necessary to run any application in English.
Installation
------------
Atlas itself is a bash script, but it can be installed in a couple of
different ways:
First, ensure ``git`` is installed and available in ``PATH`` because atlas
relies on it.
**Install as an ``npm`` package**
Install from npm:
.. code:: sh
npm install @edx/openedx-atlas
Then add ``node_modules/.bin`` to your ``PATH``.
Verify that is installed via ``atlas --help``.
**Install directly from GitHub releases**
* Download ``atlas`` from the `latest release <https://github.com/openedx/openedx-atlas/releases/latest/>`_, or from the `main branch <https://github.com/openedx/openedx-atlas/blob/main/atlas>`_:
.. code:: sh
curl -L https://github.com/openedx/openedx-atlas/releases/latest/download/atlas -o atlas
* Allow execution ``chmod +x atlas``
* Either add ``atlas`` to your ``PATH``, or run using ``./atlas``
Usage
-----
The help message below is copied from both ``atlas --help``. It's updated
regularly and useful to understand ``atlas`` at a glance.
.. code::
Atlas is a CLI tool that has essentially one command: `atlas pull`
Configuration file:
Atlas defaults to using a configuration file named `atlas.yml` placed
in the root directory. Configuration file:
pull:
repository: <organization-name>/<repository-name>
revision: <git-revision>
directory: <repo-directory-name>:<local-dir-name> ...
filter: <pattern> ...
expand_glob: 0
Atlas can also use a configuration file in a different path using the `--config` flag
after `atlas`: `atlas pull --config config.yml`.
Atlas can also be used without a configuration file by using the flags below after
`atlas pull`.
Positional arguments DIRECTORY MAPPINGS ...
One or more directory map pair separated by a colon (:) e.g. FROM_DIR:TO_DIR.
The first directory (FROM_DIR) represents a directory in the git repository.
The second directory (TO_DIR) represents a local directory to copy files to.
At least one directory pair is required:
$ atlas pull frontend-app-learning/messages:learning-app frontend-lib-test/messages:test-lib
This syntax is inspired by the `docker --volume from_dir:to_dir` mounting syntax.
Options:
`-r` or `--repository`:
slug of the GitHub repository to pull from. Defaults 'openedx/openedx-translations'.
`-n` or `--revision`:
Git revision to pull from. Currently only branches and tags are supported. Defaults to 'main'.
This option name used to be `-b` or `--branch`. The deprecated name will be removed in a future release.
`-f` or `--filter`:
A comma-separated (or space-separated) list of patterns match files and sub-directories.
This is mainly useful to filter specific languages to download.
The same filter is applied to all DIRECTORY MAPPINGS arguments.
`--filter=fr_CA,ar,es_419` will match both directories named 'es_419' and
files named 'es_419.json' among others
`-g` or `--expand-glob`:
Expand glob pattern e.g. 'atlas pull translations/*/done' to 'atlas pull translations/DoneXBlock/done'
if it exists.
Example:
$ cd frontend-app-learning/src/i18n/messages
$ atlas pull --filter=fr_CA,ar,es_419 \
translations/frontend-app-learning/src/i18n/messages:frontend-app-learning \
translations/frontend-component-header/src/i18n/messages:frontend-component-header
Will result in the following tree:
├── frontend-app-learning
│ ├── ar.json
│ ├── es_419.json
│ └── fr_CA.json
└── frontend-component-header
├── ar.json
├── es_419.json
└── fr_CA.json
Commands:
pull pull
-h, --help
--version
Running Automated Tests Locally
-------------------------------
**Install**
* `ShellSpec <https://github.com/shellspec/shellspec#installation>`_
* `ShellCheck <https://github.com/koalaman/shellcheck#installing>`_
* `getoptions <https://github.com/ko1nksm/getoptions#installation>`_
**Run**
* ``make test``: run all tests
* ``make performance_tests``: run performance tests which pulls from GitHub.com/openedx
* ``make unit_tests``: run fast unit tests without external dependency
Usage Examples
--------------
There's a couple of patterns that are useful to imitate when using Atlas
depending on the use case. ``atlas pull`` is most commonly implemented in
``Makefile``, however it can be also used in ``Dockerfile`` builds or any
other automation tool.
Python Applications
*******************
TBD
Micro-frontends
***************
TBD
Releasing a New Version
-----------------------
This repository uses `semantic versioning <https://semver.org/>`_ with the aid of
`semantic release <https://github.com/semantic-release/semantic-release/>`_ to automate the process.
To release a new version, use the `conventional commits <https://open-edx-proposals.readthedocs.io/en/latest/oep-0051-bp-conventional-commits.html>`_ and the ``release.yml`` GitHub action will
automatically create a new release and upload the ``atlas`` executable.
Note: The ``atlas --version`` command only outputs the version if it's downloaded from a GitHub release. Otherwise, it
will output ``unreleased``.
License
-------
The code in this repository is licensed under the AGPL 3.0 unless otherwise noted.
Please see ``LICENSE`` for details.
How To Contribute
-----------------
Contributions are very welcome.
Please read
`How To Contribute <https://openedx.atlassian.net/wiki/spaces/COMM/pages/941457737/How+to+start+contributing+to+the+Open+edX+code+base>`_
for details.
Getting Help
------------
Have a question about this repository, or about Open edX in general? Please refer to this
`list of resources`_ if you need any assistance.
.. _list of resources: https://open.edx.org/getting-help
Raw data
{
"_id": null,
"home_page": "https://github.com/openedx/openedx-atlas",
"name": "openedx-atlas",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Open edX project",
"author_email": "oscm@axim.org",
"download_url": "https://files.pythonhosted.org/packages/36/09/18d97a00361e7e0befea7729843deba6c56147393e2e2c998834247e05e9/openedx-atlas-0.6.0.tar.gz",
"platform": null,
"description": "openedx-atlas\n#############\n\nAn Open edX CLI tool for moving translation files from openedx-translations.\n\nOverview\n--------\n\nOEP-58 proposes changes to the way the Open edX Organization organizes and maintains\ntranslation files. Atlas is an Open edX CLI tool that uses git's sparse-checkout to\ndownload directories with the repository openedx-translations. These directories\ncorrespond to repositories within the GitHub openedx organization. They contain\ntranslation files downloaded from Transifex that have been translated by the Open edX\nTranslations Working Group.\n\nAtlas is intended for both development and deployment, and is meant to be used after\ncloning a repository with translation files kept in openedx-translations. For instance,\nwhen building a docker image or testing localization strings locally. It should not be\nnecessary to run any application in English.\n\nInstallation\n------------\n\nAtlas itself is a bash script, but it can be installed in a couple of\ndifferent ways:\n\nFirst, ensure ``git`` is installed and available in ``PATH`` because atlas\nrelies on it.\n\n**Install as an ``npm`` package**\n\nInstall from npm:\n\n.. code:: sh\n\n npm install @edx/openedx-atlas\n\nThen add ``node_modules/.bin`` to your ``PATH``.\n\nVerify that is installed via ``atlas --help``.\n\n**Install directly from GitHub releases**\n\n* Download ``atlas`` from the `latest release <https://github.com/openedx/openedx-atlas/releases/latest/>`_, or from the `main branch <https://github.com/openedx/openedx-atlas/blob/main/atlas>`_:\n\n.. code:: sh\n\n curl -L https://github.com/openedx/openedx-atlas/releases/latest/download/atlas -o atlas\n\n* Allow execution ``chmod +x atlas``\n* Either add ``atlas`` to your ``PATH``, or run using ``./atlas``\n\nUsage\n-----\n\nThe help message below is copied from both ``atlas --help``. It's updated\nregularly and useful to understand ``atlas`` at a glance.\n\n.. code::\n\n Atlas is a CLI tool that has essentially one command: `atlas pull`\n\n Configuration file:\n\n Atlas defaults to using a configuration file named `atlas.yml` placed\n in the root directory. Configuration file:\n\n pull:\n repository: <organization-name>/<repository-name>\n revision: <git-revision>\n directory: <repo-directory-name>:<local-dir-name> ...\n filter: <pattern> ...\n expand_glob: 0\n\n Atlas can also use a configuration file in a different path using the `--config` flag\n after `atlas`: `atlas pull --config config.yml`.\n\n Atlas can also be used without a configuration file by using the flags below after\n `atlas pull`.\n\n Positional arguments DIRECTORY MAPPINGS ...\n\n One or more directory map pair separated by a colon (:) e.g. FROM_DIR:TO_DIR.\n\n The first directory (FROM_DIR) represents a directory in the git repository.\n The second directory (TO_DIR) represents a local directory to copy files to.\n\n At least one directory pair is required:\n\n $ atlas pull frontend-app-learning/messages:learning-app frontend-lib-test/messages:test-lib\n\n This syntax is inspired by the `docker --volume from_dir:to_dir` mounting syntax.\n\n Options:\n\n `-r` or `--repository`:\n slug of the GitHub repository to pull from. Defaults 'openedx/openedx-translations'.\n\n `-n` or `--revision`:\n Git revision to pull from. Currently only branches and tags are supported. Defaults to 'main'.\n\n This option name used to be `-b` or `--branch`. The deprecated name will be removed in a future release.\n\n `-f` or `--filter`:\n A comma-separated (or space-separated) list of patterns match files and sub-directories.\n This is mainly useful to filter specific languages to download.\n\n The same filter is applied to all DIRECTORY MAPPINGS arguments.\n\n `--filter=fr_CA,ar,es_419` will match both directories named 'es_419' and\n files named 'es_419.json' among others\n\n `-g` or `--expand-glob`:\n Expand glob pattern e.g. 'atlas pull translations/*/done' to 'atlas pull translations/DoneXBlock/done'\n if it exists.\n\n Example:\n\n $ cd frontend-app-learning/src/i18n/messages\n $ atlas pull --filter=fr_CA,ar,es_419 \\\n translations/frontend-app-learning/src/i18n/messages:frontend-app-learning \\\n translations/frontend-component-header/src/i18n/messages:frontend-component-header\n\n Will result in the following tree:\n\n \u251c\u2500\u2500 frontend-app-learning\n \u2502 \u251c\u2500\u2500 ar.json\n \u2502 \u251c\u2500\u2500 es_419.json\n \u2502 \u2514\u2500\u2500 fr_CA.json\n \u2514\u2500\u2500 frontend-component-header\n \u251c\u2500\u2500 ar.json\n \u251c\u2500\u2500 es_419.json\n \u2514\u2500\u2500 fr_CA.json\n\n\n\n Commands:\n pull pull\n -h, --help\n --version\n\n\nRunning Automated Tests Locally\n-------------------------------\n\n**Install**\n\n* `ShellSpec <https://github.com/shellspec/shellspec#installation>`_\n* `ShellCheck <https://github.com/koalaman/shellcheck#installing>`_\n* `getoptions <https://github.com/ko1nksm/getoptions#installation>`_\n\n**Run**\n\n* ``make test``: run all tests\n* ``make performance_tests``: run performance tests which pulls from GitHub.com/openedx\n* ``make unit_tests``: run fast unit tests without external dependency\n\nUsage Examples\n--------------\n\nThere's a couple of patterns that are useful to imitate when using Atlas\ndepending on the use case. ``atlas pull`` is most commonly implemented in\n``Makefile``, however it can be also used in ``Dockerfile`` builds or any\nother automation tool.\n\nPython Applications\n*******************\n\nTBD\n\n\nMicro-frontends\n***************\n\nTBD\n\n\nReleasing a New Version\n-----------------------\nThis repository uses `semantic versioning <https://semver.org/>`_ with the aid of\n`semantic release <https://github.com/semantic-release/semantic-release/>`_ to automate the process.\n\nTo release a new version, use the `conventional commits <https://open-edx-proposals.readthedocs.io/en/latest/oep-0051-bp-conventional-commits.html>`_ and the ``release.yml`` GitHub action will\nautomatically create a new release and upload the ``atlas`` executable.\n\nNote: The ``atlas --version`` command only outputs the version if it's downloaded from a GitHub release. Otherwise, it\nwill output ``unreleased``.\n\nLicense\n-------\n\nThe code in this repository is licensed under the AGPL 3.0 unless otherwise noted.\n\nPlease see ``LICENSE`` for details.\n\nHow To Contribute\n-----------------\n\nContributions are very welcome.\n\nPlease read\n`How To Contribute <https://openedx.atlassian.net/wiki/spaces/COMM/pages/941457737/How+to+start+contributing+to+the+Open+edX+code+base>`_\nfor details.\n\nGetting Help\n------------\n\nHave a question about this repository, or about Open edX in general? Please refer to this\n`list of resources`_ if you need any assistance.\n\n.. _list of resources: https://open.edx.org/getting-help\n\n\n",
"bugtrack_url": null,
"license": "AGPL 3.0",
"summary": "An Open edX CLI tool for moving translation files from openedx-translations.",
"version": "0.6.0",
"project_urls": {
"Homepage": "https://github.com/openedx/openedx-atlas"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5842f10f6e6f9cd970a63e06e9612822f2d988a74a5e90c2813d46273ceae8c7",
"md5": "bffdd7b7be99f890459e98fd48c994ce",
"sha256": "541e7537748d8729b858d5f4193791804d5de452b551af4caf96812af3b29a6e"
},
"downloads": -1,
"filename": "openedx_atlas-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bffdd7b7be99f890459e98fd48c994ce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 21761,
"upload_time": "2024-01-17T14:19:07",
"upload_time_iso_8601": "2024-01-17T14:19:07.196894Z",
"url": "https://files.pythonhosted.org/packages/58/42/f10f6e6f9cd970a63e06e9612822f2d988a74a5e90c2813d46273ceae8c7/openedx_atlas-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "360918d97a00361e7e0befea7729843deba6c56147393e2e2c998834247e05e9",
"md5": "1f40c0204471efdb486faedaec230968",
"sha256": "183a6709d166d69da7b168f413e2043162f7df3d51e4fb0b65ff4c6c1e141026"
},
"downloads": -1,
"filename": "openedx-atlas-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "1f40c0204471efdb486faedaec230968",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22377,
"upload_time": "2024-01-17T14:19:08",
"upload_time_iso_8601": "2024-01-17T14:19:08.848408Z",
"url": "https://files.pythonhosted.org/packages/36/09/18d97a00361e7e0befea7729843deba6c56147393e2e2c998834247e05e9/openedx-atlas-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-17 14:19:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openedx",
"github_project": "openedx-atlas",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "openedx-atlas"
}
JSON
