зеркало из https://github.com/mozilla/pontoon.git
No bug - Add a guide to first Pontoon contribution. (#1532)
This adds a new guide to start contributing to Pontoon, detailing all the needed steps and giving pointers to useful documentation. It also reworks the documentation home page to be more helpful to people depending on what they are looking for. And it does the same for the readme file.
This commit is contained in:
Adrian Gaudebert
GitHub
Родитель
e25c31f463
Коммит
1dd62bc8f9
58
README.md
58
README.md
|
|
@ -5,44 +5,58 @@ Pontoon is a translation management system used and developed by the
|
|||
specializes in open source localization that is driven by the community and
|
||||
uses version-control systems for storing translations.
|
||||
|
||||
Check out our documentation to learn how to:
|
||||
[📚 **Documentation**](https://mozilla-pontoon.readthedocs.io/)
|
||||
|
||||
* [Localize with Pontoon](https://mozilla-l10n.github.io/localizer-documentation/tools/pontoon/)
|
||||
* [Make your projects localizable with Pontoon](https://mozilla-pontoon.readthedocs.io/en/latest/user/localizing-your-projects.html)
|
||||
|
||||
## Installation
|
||||
## Installing Pontoon
|
||||
|
||||
Our [installation documentation](https://mozilla-pontoon.readthedocs.io/) is available on `Read the Docs`:
|
||||
|
||||
* For local development, see [developer setup](http://mozilla-pontoon.readthedocs.io/en/latest/dev/setup.html) using `Docker`
|
||||
* For production installation, see [deployment documentation](http://mozilla-pontoon.readthedocs.io/en/latest/admin/deployment.html)
|
||||
* For quick and easy deployment on the `Heroku` platform, click this button:
|
||||
If you are looking to host your own instance of Pontoon, there are several ways to do so.
|
||||
To deploy Pontoon to Heroku without leaving your web browser, click the **Deploy to
|
||||
Heroku** button below.
|
||||
|
||||
[](https://heroku.com/deploy)
|
||||
|
||||
## Contributing
|
||||
Alternatively, you can deploy to Heroku manually by following our
|
||||
[Deployment Documentation](https://mozilla-pontoon.readthedocs.io/en/latest/admin/deployment.html).
|
||||
|
||||
We don't have documentation for deploying to other platforms yet, so we recommend that
|
||||
you read the previously linked documentation and adapt it for your needs.
|
||||
|
||||
If you only want to deploy a **local instance of Pontoon**, for development or
|
||||
testing for example, see our
|
||||
[Developer Setup using Docker](https://mozilla-pontoon.readthedocs.io/en/latest/dev/setup.html).
|
||||
Please note that you should **not** deploy a production instance with Docker.
|
||||
|
||||
|
||||
## Contributing to Pontoon
|
||||
|
||||
Do you want to help us make Pontoon better? We are very glad!
|
||||
|
||||
Start by [installing Pontoon locally using Docker](https://mozilla-pontoon.readthedocs.io/en/latest/dev/setup.html). Once you have a working local environment, take a look at our [mentored bugs](https://wiki.mozilla.org/Webdev/GetInvolved/pontoon.mozilla.org). It is often better to start with those bugs, as they tend to be easier, and someone is committed to helping you get it done. To start working on a bug, verify that it isn't already assigned to someone else, and then ask on the bug for it to be assigned to you.
|
||||
|
||||
Before you start writing code, make sure to read our [contribution docs](https://mozilla-pontoon.readthedocs.io/en/latest/dev/contributing.html). It contains information on how to style code, how to run tests, how to name your commits, etc. All the things you need to know if you want your work to be merged into Pontoon!
|
||||
|
||||
Pontoon developers hang around in the `#pontoon` channel on [Mozilla's IRC server](https://wiki.mozilla.org/IRC). Please [join us there](https://cbe001.chat.mibbit.com/?url=irc:%2F%2Firc.mozilla.org%2Fpontoon) if you want to ask questions!
|
||||
To help you get started with contributing, we wrote
|
||||
[**The Guide to your First Contribution to Pontoon**](https://mozilla-pontoon.readthedocs.io/en/latest/dev/first-contribution.html).
|
||||
It contains all the information you need to know to install Pontoon, populate its
|
||||
database, run tests, and send your contribution.
|
||||
|
||||
If you want to go further, you can:
|
||||
|
||||
* Check out development roadmap on the [wiki](http://wiki.mozilla.org/Pontoon)
|
||||
* Check out development roadmap on the [wiki](https://wiki.mozilla.org/Pontoon)
|
||||
* File a [bug](https://bugzilla.mozilla.org/enter_bug.cgi?product=Webtools&component=Pontoon&rep_platform=all&op_sys=all)
|
||||
* Check [existing bugs](https://bugzilla.mozilla.org/buglist.cgi?product=Webtools&component=Pontoon&resolution=---&list_id=13740920)
|
||||
|
||||
## Servers (used for Mozilla projects only)
|
||||
|
||||
* [Staging](https://mozilla-pontoon-staging.herokuapp.com/)
|
||||
* [Production](https://pontoon.mozilla.org/)
|
||||
* See Mozilla's Pontoon servers:
|
||||
* [Staging](https://mozilla-pontoon-staging.herokuapp.com/)
|
||||
* [Production](https://pontoon.mozilla.org/)
|
||||
|
||||
## License
|
||||
|
||||
This software is licensed under the
|
||||
[New BSD License](http://creativecommons.org/licenses/BSD/). For more
|
||||
[New BSD License](https://creativecommons.org/licenses/BSD/). For more
|
||||
information, read [LICENSE](https://github.com/mozilla/pontoon/blob/master/LICENSE).
|
||||
|
||||
|
||||
## Screenshots
|
||||
|
||||
|
||||
*Teams dashboard*
|
||||
|
||||
|
||||
*Translation app*
|
||||
|
|
|
|||
|
|
@ -77,7 +77,7 @@ language = None
|
|||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
exclude_patterns = ['_build']
|
||||
exclude_patterns = ['_build', 'venv']
|
||||
|
||||
# The reST default role (used for this markup: `text`) to use for all
|
||||
# documents.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,213 @@
|
|||
The Guide to your First Contribution to Pontoon
|
||||
===============================================
|
||||
|
||||
Welcome to Pontoon!
|
||||
|
||||
This document is going to guide you as you discover Pontoon and make
|
||||
valuable contributions. It will walk you step by step until you are in a
|
||||
position to write code that you can reliably run, test, and send for
|
||||
review.
|
||||
|
||||
1. Make sure it's a good match
|
||||
------------------------------
|
||||
|
||||
*Before contributing to an open source project, it is important to make
|
||||
sure that the project uses technologies that you know and want to learn more about.*
|
||||
|
||||
Pontoon is a web application, with both back-end and front-end code. The
|
||||
two languages we use are **Python** (back-end) and **JavaScript**
|
||||
(front-end). On the back-end, we use the **Django** framework. On the
|
||||
front-end, we use the **React** framework. To be able to contribute, you
|
||||
will want to have knowledge of either Python and Django or JavaScript
|
||||
and React. Having experience with both pairs is of course even better!
|
||||
|
||||
We use **git** to version our code, and we use **GitHub** to handle pull
|
||||
requests and code reviews. Basic knowledge of git is required to be able
|
||||
to send your contributions our way.
|
||||
|
||||
+--------------+-------------------+-------------------+
|
||||
| Skill | Expected Level | Notes |
|
||||
+==============+===================+===================+
|
||||
| git | Basic knowledge | |
|
||||
+--------------+-------------------+-------------------+
|
||||
| Python | Some experience | Python 2 & 3 |
|
||||
+--------------+-------------------+-------------------+
|
||||
| Django | Basic knowledge | |
|
||||
+--------------+-------------------+-------------------+
|
||||
| JavaScript | Some experience | ECMAScript 2018 |
|
||||
+--------------+-------------------+-------------------+
|
||||
| React | Basic knowledge | |
|
||||
+--------------+-------------------+-------------------+
|
||||
|
||||
2. Install Pontoon
|
||||
------------------
|
||||
|
||||
*In order to be able to contribute code to an open source project, you
|
||||
first need to be able to run that project on your computer.*
|
||||
|
||||
The recommended method of installing Pontoon is using ``docker`` and our
|
||||
scripts. It is straightforward if your computer is running with Linux or
|
||||
macOS, in which case you can just follow the instructions in our `Developer Setup
|
||||
Documentation <https://mozilla-pontoon.readthedocs.io/en/latest/dev/setup.html>`__.
|
||||
|
||||
If you are running Windows on your computer, installing Pontoon might be
|
||||
more difficult. You need to install a version of docker that is
|
||||
compatible with your version of Windows, and you won't be able to use
|
||||
our nice ``Makefile`` commands without installing some tools. We sadly
|
||||
don't have documentation about installing on Windows, so you'll have to
|
||||
use the previously linked documentation and adapt it for your particular
|
||||
version of Windows.
|
||||
|
||||
3. Populate your database
|
||||
-------------------------
|
||||
|
||||
*After installing a tool, it is likely that its database is empty. You
|
||||
will need to create some data in order to have things show up in the
|
||||
interface.*
|
||||
|
||||
Once Pontoon is installed and you have it running, you will want to
|
||||
create some data so that you can play with it, and test it in action.
|
||||
You can create any kind of data you want, of course, but to make it
|
||||
easier we have a special git repository that we made for testing
|
||||
Pontoon. Here are the steps to add that project to your Pontoon
|
||||
instance:
|
||||
|
||||
1. Log in to your local instance with the superuser account you created during the previous step.
|
||||
2. Click the avatar in the top-right corner, and in the menu click "Admin".
|
||||
3. You will see the Admin panel, with a table of projects that will likely be empty. Click the "Add New Project" button.
|
||||
4. Fill the project creation form as follows:
|
||||
|
||||
1. Name: Pontoon Test
|
||||
2. Slug (auto-filled): pontoon-test
|
||||
3. Locales: select Slovenian (sl), then add any locales you want
|
||||
4. Repositories
|
||||
|
||||
1. URL: https://github.com/mathjazz/pontoon-test
|
||||
2. Download prefix: https://raw.githubusercontent.com/mathjazz/pontoon-test/master/{locale\_code}
|
||||
3. Public Repository Website: https://github.com/mathjazz/pontoon-test
|
||||
|
||||
5. Leave the rest as it is, then scroll to the bottom of the page, and click the "Save Project" button.
|
||||
6. Once the project is saved, scroll to the bottom of the page again, and click the "Sync" button. This will pull the data from the repository, and create entries for each of the locales you have enabled.
|
||||
7. And that's it! You should now have a project enabled for some locale.
|
||||
|
||||
4. Verify your setup
|
||||
--------------------
|
||||
|
||||
*Setting up a project means more than installing it: it also means
|
||||
making sure that the tool runs and that tests pass.*
|
||||
|
||||
Once you have successfully installed and populated Pontoon on your
|
||||
computer, you will need to make a few verifications. First and foremost,
|
||||
make sure the site works correctly, and the data you created previously
|
||||
shows up. Make sure you can log in, that you can send some translations,
|
||||
that projects appear on the dashboards, etc.
|
||||
|
||||
Second, you will want to run the tests and make sure they pass. We have
|
||||
a few test suites for Pontoon, some for the front-end, others for the
|
||||
back-end, as well as a few code-quality tests. To run all of the tests
|
||||
(same as what will happen when you open a pull request in GitHub), use
|
||||
the command ``make test``.
|
||||
|
||||
When you have successfully verified that your setup works correctly, you
|
||||
can safely move to the next part.
|
||||
|
||||
5. Choose a bug to work on
|
||||
--------------------------
|
||||
|
||||
*You are now ready to make a contribution! Open source projects usually
|
||||
have a list of mentored bugs that are appropriate to work on first, and
|
||||
on which mentors will be available to help you.*
|
||||
|
||||
Work that needs to be done on Pontoon is tracked in
|
||||
`bugzilla <https://bugzilla.mozilla.org/>`__, Mozilla's bug tracking
|
||||
software. You will need to create an account there in order to be
|
||||
assigned to a bug.
|
||||
|
||||
We maintain a list of what we deem "good first bugs". They are marked as
|
||||
mentored on bugzilla, and can be found quickly on our `Pontoon wiki
|
||||
page <https://wiki.mozilla.org/L10n:Pontoon#Get_involved>`__ or through
|
||||
`this bugzilla
|
||||
search <https://bugzilla.mozilla.org/buglist.cgi?f1=bug_mentor&list_id=15050149&o1=isnotempty&resolution=---&classification=Server%20Software&query_format=advanced&emailbug_mentor1=1&component=Pontoon&product=Webtools>`__.
|
||||
Look through that list for unassigned bugs (marked as ``NEW``), choose
|
||||
one that is appealing to you and seems adapted to your skill set, then
|
||||
comment on that bug asking to be assigned to it. Feel free to start
|
||||
working on it right away — even if you end up not being assigned for
|
||||
some reason, it will still be good experience for you.
|
||||
|
||||
6. Read the contributing rules
|
||||
------------------------------
|
||||
|
||||
*Most projects have strict contributing rules, and your contributions
|
||||
risk not being accepted if you don't respect them.*
|
||||
|
||||
To make developer's lives easier, we enforce a few contribution rules
|
||||
around Pontoon. They range from how to style your code to how to write
|
||||
commit messages. All these rules are written in our `Contributing
|
||||
Documentation <https://mozilla-pontoon.readthedocs.io/en/latest/dev/contributing.html>`__.
|
||||
Please read it before opening a pull request!
|
||||
|
||||
There is more documentation around Pontoon, and it is often worth
|
||||
reading it, if only to understand better how the tool works and how and
|
||||
where to make your contributions. Here are a few links to important
|
||||
documentation resources:
|
||||
|
||||
- If you want to work on the front-end, it is important that you read
|
||||
the `Front-End
|
||||
Documentation <https://github.com/mozilla/pontoon/tree/master/frontend>`__.
|
||||
- Most of the documentation around installing and developing can be
|
||||
found in `Pontoon's
|
||||
Documentation <https://mozilla-pontoon.readthedocs.io/en/latest/>`__.
|
||||
- For documentation about using Pontoon to localize, see `How to use
|
||||
Pontoon <https://mozilla-l10n.github.io/localizer-documentation/tools/pontoon/>`__.
|
||||
- For documentation about exposing a project on Pontoon, see `How to
|
||||
localize your
|
||||
projects <https://mozilla-pontoon.readthedocs.io/en/latest/user/localizing-your-projects.html>`__.
|
||||
- For documentation about managing communities in Pontoon, see `Working
|
||||
with
|
||||
Pontoon <https://mozilla-l10n.github.io/documentation/tools/pontoon/>`__.
|
||||
|
||||
7. Communicate with us
|
||||
----------------------
|
||||
|
||||
*Open source projects are usually built around a community of people.
|
||||
Communicating with that community is an important part of contributing
|
||||
to such projects.*
|
||||
|
||||
There are two main places where we communicate about Pontoon's
|
||||
development. The first one is IRC, used for real-time chat, quick
|
||||
questions, side-track conversations, etc. We hang on the #pontoon
|
||||
channel on `Mozilla's IRC server <https://wiki.mozilla.org/IRC>`__.
|
||||
|
||||
The second is discourse, a forum platform that we use for more long-term
|
||||
conversations. We use `Mozilla's community
|
||||
discourse <https://discourse.mozilla.org/>`__ instance, posting in the
|
||||
`pontoon category <https://discourse.mozilla.org/c/pontoon>`__.
|
||||
|
||||
These are both places that we strongly encourage you to join, and they
|
||||
are where you should introduce yourself, ask questions, show your work,
|
||||
etc.
|
||||
|
||||
Pontoon's core developer team is currently composed of Matjaž and
|
||||
Adrian, with occasional help from other members of Mozilla's L10n team,
|
||||
Axel and Staś. We also receive invaluable help from community members.
|
||||
|
||||
+------------+----------+--------------------------+------------+-----------------------------------------------+
|
||||
| | Name | ROLE | IRC | github |
|
||||
+============+==========+==========================+============+===============================================+
|
||||
| |image4| | Matjaž | Pontoon Core Developer | mathjazz | `mathjazz <https://github.com/mathjazz/>`__ |
|
||||
+------------+----------+--------------------------+------------+-----------------------------------------------+
|
||||
| |image5| | Adrian | Pontoon Core Developer | adrian | `adngdb <https://github.com/adngdb/>`__ |
|
||||
+------------+----------+--------------------------+------------+-----------------------------------------------+
|
||||
| |image6| | Axel | L10n Tech Lead | Pike | `Pike <https://github.com/Pike/>`__ |
|
||||
+------------+----------+--------------------------+------------+-----------------------------------------------+
|
||||
| |image7| | Staś | Fluent Core Developer | stas | `stasm <https://github.com/stasm/>`__ |
|
||||
+------------+----------+--------------------------+------------+-----------------------------------------------+
|
||||
|
||||
.. |image0| image:: https://avatars2.githubusercontent.com/u/626716?s=32&v=4
|
||||
.. |image1| image:: https://avatars1.githubusercontent.com/u/328790?s=32&v=4
|
||||
.. |image2| image:: https://avatars3.githubusercontent.com/u/43494?s=32&v=4
|
||||
.. |image3| image:: https://avatars2.githubusercontent.com/u/265818?s=32&v=4
|
||||
.. |image4| image:: https://avatars2.githubusercontent.com/u/626716?s=32&v=4
|
||||
.. |image5| image:: https://avatars1.githubusercontent.com/u/328790?s=32&v=4
|
||||
.. |image6| image:: https://avatars3.githubusercontent.com/u/43494?s=32&v=4
|
||||
.. |image7| image:: https://avatars2.githubusercontent.com/u/265818?s=32&v=4
|
||||
|
|
@ -24,7 +24,7 @@ Prerequisites
|
|||
Quickstart
|
||||
----------
|
||||
|
||||
1. Clone your `fork <http://help.github.com/fork-a-repo/>` of Pontoon repository::
|
||||
1. Clone your `fork <http://help.github.com/fork-a-repo/>`_ of Pontoon repository::
|
||||
|
||||
$ git clone https://github.com/YOUR-USERNAME/pontoon.git
|
||||
|
||||
|
|
|
|||
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 157 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 173 KiB |
|
|
@ -5,31 +5,47 @@ Pontoon is a translation management system used and developed by the Mozilla
|
|||
localization community. It can handle any project that uses one of the
|
||||
supported file formats:
|
||||
|
||||
- .dtd
|
||||
- .ftl (Fluent)
|
||||
- .inc
|
||||
- .ini
|
||||
- .json (WebExtensions)
|
||||
- .lang
|
||||
- .po (Gettext)
|
||||
- .properties
|
||||
- .xliff
|
||||
- .xml (Android)
|
||||
+-------+---------------+-------------+--------+-----------------------+
|
||||
| .dtd | .ftl (Fluent) | .inc | .ini | .json (WebExtensions) |
|
||||
+-------+---------------+-------------+--------+-----------------------+
|
||||
| .lang | .po (Gettext) | .properties | .xliff | .xml (Android) |
|
||||
+-------+---------------+-------------+--------+-----------------------+
|
||||
|
||||
Pontoon can pull strings it needs to translate from an external source, and write
|
||||
them back periodically. Typically these external sources are version control
|
||||
repositories that store the strings for an application. Supported external
|
||||
sources include:
|
||||
sources include **Git**, **Mercurial** and **Subversion**.
|
||||
|
||||
- Git
|
||||
- Mercurial
|
||||
- Subversion
|
||||
Contributing
|
||||
------------
|
||||
|
||||
If you are interested in contributing to Pontoon's code, start with
|
||||
:doc:`dev/first-contribution`.
|
||||
|
||||
Deploying
|
||||
---------
|
||||
|
||||
If you want to deploy your own instance of Pontoon, read the :doc:`admin/deployment`
|
||||
section.
|
||||
|
||||
Once you have a running instance, you will likely want to learn about
|
||||
:doc:`user/localizing-your-projects`, and then about
|
||||
`How to manage communities <https://mozilla-l10n.github.io/documentation/tools/pontoon/>`_.
|
||||
|
||||
Localizing
|
||||
----------
|
||||
|
||||
If you're looking for help on using Pontoon for localizing projects, whether on
|
||||
Mozilla's instance or any other, you can read our
|
||||
`How to use Pontoon <https://mozilla-l10n.github.io/localizer-documentation/tools/pontoon/>`_
|
||||
documentation.
|
||||
|
||||
Contents
|
||||
--------
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
dev/first-contribution
|
||||
dev/setup
|
||||
dev/contributing
|
||||
admin/deployment
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче