Adding New Documents¶
Writing Documents¶
Before you start writing documents:
Make sure you have all the necessary information and tools you need to get started
Check the current documents carefully to make sure you’re not repeating something somebody has already said
Familiarize yourself with reStructuredText and the recommended document style
Once you’re ready to get started, you can start working with Gitlab
Working With Gitlab¶
Documents are managed in the Funkwhale Gitlab repository along with the code. In order to add new documents, you will need to follow this process:
Signing up to Gitlab¶
Before you can contribute documents to Funkwhale, you will need to set up an account on the project’s Gitlab. 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 to enable easy management of your repository
Fork the project¶
Once you have set up an account, you can fork the project to create a copy of the repository that you can make changes to.
Navigate to the Funkwhale repository
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 the Repository¶
Once you have successfully forked the project, you can safely download a copy of this to your local computer to create documents.
# 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 merge it later
# 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 Documents to Your Branch¶
When you’ve got your repository all set up, you can start writing your documents. Remember to keep in mind who you are writing for when you are writing, and check your syntax works.
Once you’ve written what you need to write, you can push these changes to your forked repository:
# 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]
Create a Merge Request¶
Once you’ve pushed all of your documents, you can create a Merge Request to request the documents be merged into the official Funkwhale develop branch.
Navigate to the Funkwhale repository
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.