JabRef / user-documentation

User documentation of JabRef
https://docs.jabref.org/
Creative Commons Attribution Share Alike 4.0 International
47 stars 112 forks source link

Added contribution documentation to describe running workflows thru github #530

Closed Tridecatrix closed 1 month ago

Tridecatrix commented 1 month ago

File changes: en/contributing/how-to-improve-the-help-page.md .gitbook/assets/run-workflow-thru-github.png

Found a simpler way to run the workflows on a local fork of the repo that doesn't require using act, docker or cloning another repo. Thought I'd request including it in the contributor documentation.

It is possible that this is rather standard for people more accustomed to Github workflows (I personally am more used to Gitlab) but may help other new contributors ¯_(ツ)_/¯

koppor commented 1 month ago

With the new workflow, it should run automatically on each push? --> https://github.com/JabRef/user-documentation/blob/main/.github/workflows/check-links.yaml

Maybe refine that contributors need to check the Actions tab?

Moreover, I also added running when a PR is created.

Tridecatrix commented 1 month ago

Ah yes indeed, will update.

Tridecatrix commented 1 month ago

Think that this also actually deprecates the existing documentation saying "how to find broken links" and "how to find markdown errors" by running the workflows or their scripts manually with docker/act/npm? Surely just delete those?

So proposed: remove "How to find broken links" and "How to find Markdown errors" sections, and create a single section "Github workflows" under Advanced Contribution Hints that clarifies using the workflows.

koppor commented 1 month ago

Think that this also actually deprecates the existing documentation saying "how to find broken links" and "how to find markdown errors" by running the workflows or their scripts manually with docker/act/npm? Surely just delete those?

Do you have a link? I don't remember those. I would propose to delete as they are very expert and not for the average person.

So proposed: remove "How to find broken links" and "How to find Markdown errors" sections, and create a single section "Github workflows" under Advanced Contribution Hints that clarifies using the workflows.

Yes!

Tridecatrix commented 1 month ago

Alright, I think I am finally done here! Do briefly check what I've written but I also decided to include a part about links possibly failing in check links and not to worry about it if it's not your fault (a-la what we discussed re: lycheeignore and not flooding contributors with issues about broken links), as well as adding external resource links to lycheeignore if you add any.

I also actually renamed the Check links workflow to just "Check links" instead of "Check external href links in the documentation" for succinctness reasons (in .github/workflows/check_links.yaml). Should actually create a seperate PR for that tbh but can't be bothered, lots of effort for such a minor change.

I'll leave this for review now.