A plea for help writing the docs

Software darktable
22

First time writing something like this and it’s hard without knowing the skill level and prior knowledge of the user. Please let me know if it can be made clearer. This guide is supposed to be practical without any teaching about how git works, it’s supposed to be enough information to let people make contributions do the docs.

–

I assume that you already have a github account and have installed Git as well. Make sure that git is in your PATH by executing the command git in any terminal or cmd and checking that it doesn’t output an error such as “command not found”.

Authenticate Github

Follow the instructions for GitHub CLI at Caching your GitHub credentials in Git - GitHub Docs

Do once:

  1. Go to https://github.com/darktable-org/dtdocs
  2. Press the Fork button and then the Create fork button
  3. You will be redirected to a page with your fork of darktable docs. Press the Code button and copy the link under HTTPS.
  4. Open a terminal or cmd in your desired directory where the darktable repository will reside. Something like 'C:\Users\YourUser\Documents' or ‘/home/youruser/Documents/builds’. Both on windows and macOS/Linux you can use the following command to travel to your desired directory: cd C:\Users\YourUser\Documents\ replacing the example directory for yours.
  5. Pull the darktable repository by executing: git clone https://github.com/hats-np/dtdocs.git Change the URL for the one you copied on step 3.
  6. Now you have a copy of the darktable repository on your pc

Do every time before working on a new PR:

  1. Go to your repositories on github and select your darktable fork
  2. Press the Sync fork
  3. Open a terminal or cmd in your darktable repository directory
  4. Assure you have no pending changes by executing git status and then execute git checkout master
  5. Execute git pull

Work

  1. Open a terminal on cmd on your darktable repository directory
  2. Execute git checkout -b branch-name change branch-name for your desired branch name. This is often related to the work you’re doing. For example for this PR darkroom: Add synchronization of last edited iop to selection. by TurboGit · Pull Request #17589 · darktable-org/darktable · GitHub you could call it dt-synch-edit-docs.
  3. Do the documentation work
  4. Verify your changed files with git status. If you have more files modified than the ones you intend to submit, you can do git restore path/to/file/ do revert your changes.
  5. Execute git add -A
  6. Execute git commit -m "Added documentation for yada yada". Inside the “” you will put a small message about the work you did
  7. Execute git push --set-upstream origin branch-name Changing the branch name by the one you picked before
  8. Create your pull request by following the instructions bellow.
  9. If you need to make changes, simply repeat 3-7. For the command in step 2 you can omit -b and in step 7 you can just do git push.
  10. After you are done and your pull request is merged or you are finished with your work for this specific pull request, execute git checkout master to return to the master branch. I recommend working on only one branch/pr at a time if you don’t know how git works.

Pull request

  1. Go to Compare · darktable-org/dtdocs · GitHub
  2. Press compare across forks. Select your repository, and then the branch you just worked on.
  3. Press Create Pull Request
3 Likes
23

This looks fabulous. I will have a go over the holiday period and let you know any feedback if I get stuck. Thank you

1 Like