kopia lustrzana https://dev.funkwhale.audio/funkwhale/funkwhale
130 wiersze
4.4 KiB
ReStructuredText
130 wiersze
4.4 KiB
ReStructuredText
Adding New Documents
|
|
====================
|
|
|
|
Writing Documents
|
|
-----------------
|
|
|
|
Before you start writing documents:
|
|
|
|
- Make sure you have all the necessary information and :doc:`tools you need <tools>` to get started
|
|
- Check the `current documents <https://docs.funkwhale.audio>`_ carefully to make sure you're not repeating something somebody has already said
|
|
- Familiarize yourself with :doc:`reStructuredText <restructured>` and :doc:`the recommended document style <style>`
|
|
|
|
Once you're ready to get started, you can start :ref:`working with Gitlab <work-with-gitlab>`
|
|
|
|
.. _work-with-gitlab:
|
|
|
|
Working With Gitlab
|
|
-------------------
|
|
|
|
Documents are managed in the Funkwhale `Gitlab <https://dev.funkwhale.audio>`_ repository along with the code.
|
|
In order to add new documents, you will need to follow this process:
|
|
|
|
- :ref:`Sign up to Gitlab <sign-up>`
|
|
- :ref:`Fork the project <fork-project>`
|
|
- :ref:`Clone the Repository <clone-repo>`
|
|
- :ref:`Add documents to your branch <add-docs>`
|
|
- :ref:`Create a Merge Request <merge-request>`
|
|
|
|
.. _sign-up:
|
|
|
|
Signing up to Gitlab
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Before you can contribute documents to Funkwhale, you will need to set up an account on the
|
|
project's `Gitlab <https://dev.funkwhale.audio>`_. To do this:
|
|
|
|
- Navigate to the https://dev.funkwhale.audio
|
|
- Click on "register" to bring up the registration form
|
|
- Fill in the relevant details, or alternatively sign up with Github if you already have an account
|
|
- [Optional]: You can then `set up an SSH key <https://docs.gitlab.com/ee/ssh/>`_ to enable easy management of your :ref:`repository <clone-repo>`
|
|
|
|
.. _fork-project:
|
|
|
|
Fork the project
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
Once you have set up an account, you can `fork the project <https://help.github.com/en/articles/fork-a-repo>`_
|
|
to create a copy of the repository that you can make changes to.
|
|
|
|
- Navigate to the `Funkwhale repository <https://dev.funkwhale.audio/funkwhale/funkwhale>`_
|
|
- Click "Fork" at the top of the repository
|
|
- You will be redirected to a new version of the project. This one's all yours!
|
|
|
|
.. _clone-repo:
|
|
|
|
Clone the Repository
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Once you have successfully forked the project, you can safely download a copy of this to your local
|
|
computer to create documents.
|
|
|
|
.. code-block:: shell
|
|
|
|
# If you're using an SSH key
|
|
|
|
git clone git@dev.funkwhale.audio:your-username/funkwhale.git
|
|
|
|
# If you're using a username/password
|
|
|
|
git clone https://dev.funkwhale.audio/your-username/funkwhale.git
|
|
|
|
Once you've cloned the repository, it's a good idea to create a new branch for your documents so that
|
|
you can :ref:`merge it later <merge-request>`
|
|
|
|
.. code-block:: shell
|
|
|
|
# Create a new branch to make changes to
|
|
|
|
git checkout -b [name_of_your_new_branch]
|
|
|
|
# Push the branch up to your forked repository
|
|
|
|
git push origin [name_of_your_new_branch]
|
|
|
|
.. _add-docs:
|
|
|
|
Add Documents to Your Branch
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
When you've got your repository all set up, you can start writing your documents. Remember to keep in mind
|
|
:doc:`who you are writing for <style>` when you are writing, and :doc:`check your syntax works <restructured>`.
|
|
|
|
Once you've written what you need to write, you can push these changes to your forked repository:
|
|
|
|
.. code-block:: shell
|
|
|
|
# Add new documents to your commit
|
|
|
|
git add [list your documents here]
|
|
|
|
# Commit these to the branch
|
|
|
|
git commit -m "Add a commit message here!"
|
|
|
|
# Push the changes to your branch
|
|
|
|
git push origin [name_of_your_new_branch]
|
|
|
|
.. _merge-request:
|
|
|
|
Create a Merge Request
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Once you've pushed all of your documents, you can create a `Merge Request <https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html>`_
|
|
to request the documents be merged into the official Funkwhale develop branch.
|
|
|
|
- Navigate to the `Funkwhale repository <https://dev.funkwhale.audio/funkwhale/funkwhale>`_
|
|
- Click "Merge Requests" on the left hand side
|
|
- Click on the "New Merge Request"
|
|
- Under the "Source Branch" select your forked repository and the branch to which you've pushed changes
|
|
- Under "Target Branch", select the "develop" branch
|
|
- Click "Compare Branches and Continue"
|
|
- In the form that comes up, provide a title/description of the changes you've made
|
|
- Click "Submit Merge Request" to submit
|
|
|
|
That's it! If your merge request is successful, you will get a notification from one of the maintainers letting
|
|
you know your changes have been accepted. Sometimes, you may need to make minor corrections. Don't worry! We'll
|
|
let you know what needs correcting.
|
|
|