Modernise README #2575

penelopeysm · 2025-06-03T12:14:09Z

Modernise the README. See the Markdown preview @ https://github.com/TuringLang/Turing.jl/blob/py/readme/README.md

~~Badges are so 2010s--- I honestly don't think anybody really uses them anymore ever since GitHub Actions took over e.g. travis CI.~~ Readded

I skipped CI on this PR because this doesn't touch code.

Let me know if there's anything else I should add. Not sure if the last section ('how does it all fit together') should be part of the main docs.

github-actions · 2025-06-03T12:15:32Z

Turing.jl documentation for PR #2575 is available at:
https://TuringLang.github.io/Turing.jl/previews/PR2575/

mhauru

Greatly improved, thanks! Some discussion points to raise.

README.md

mhauru · 2025-06-05T08:59:35Z

I've also requested reviews from @yebai, for obvious reasons, and from @AoifeHughes, because a new comer's eye can be very valuable here.

yebai · 2025-06-05T09:24:13Z

I think lots of the text here can go to: https://github.com/TuringLang/.github/edit/main/profile/README.md

We could also keep the pointers for related Turing.jl papers.

.JuliaFormatter.toml

README.md

AoifeHughes · 2025-06-05T09:55:15Z

README.md


-Turing's home page, with links to everything you'll need to use Turing, is available at:
+**https://turinglang.org** contains the documentation for the broader TuringLang ecosystem.


I'd be tempted to change the wording to be a bit "friendlier" and less passive voice

Suggestions are welcome, I don't know how to make "the docs are here" much friendlier.

^^ I think saying "You can find the docs here" is friendlier than " contains docs".

The wording has been changed (twice), it should read better now.

README.md

penelopeysm · 2025-06-16T15:41:55Z

I think lots of the text here can go to: https://github.com/TuringLang/.github/edit/main/profile/README.md

Sure, I was going to work on that too. I think it's worth having info in both though (even if potentially duplicated) because some people will go to github.com/TuringLang and some people will go to github.com/TuringLang/Turing.jl (case in point: if you google for Turing.jl you will get the second link).

related Turing.jl papers.

Will add

coveralls · 2025-06-16T15:42:01Z

Pull Request Test Coverage Report for Build 16093044479

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

0 of 0 changed or added relevant lines in 0 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage remained the same at 85.665%

Totals
Change from base Build 15921717989:	0.0%
Covered Lines:	1249
Relevant Lines:	1458

💛 - Coveralls

codecov · 2025-06-16T15:45:52Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 85.60%. Comparing base (2d3f228) to head (f38201a).
Report is 1 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #2575       +/-   ##
===========================================
+ Coverage   58.53%   85.60%   +27.06%     
===========================================
  Files          22       22               
  Lines        1452     1459        +7     
===========================================
+ Hits          850     1249      +399     
+ Misses        602      210      -392

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

AoifeHughes · 2025-06-16T17:41:52Z

Personally, I’d still like to see quick start guides be part of readme. Ie just tell me the bash to install, run tests etc. I think forcing people to go off the page to find documentation increases likelihood someone just stops

penelopeysm · 2025-06-17T09:11:46Z

just tell me the bash to install, run tests etc

Done, there's a super simple example in the readme now, let me know what you think. I refrained from adding tests because Turing's tests take forever to run and the average user isn't likely to ever run them (you have to clone the repo anyway, which is not what most people do unless they're hacking on the package itself)

yebai · 2025-06-20T17:31:05Z

README.md

-See [releases](https://github.com/TuringLang/Turing.jl/releases).
+julia> @model function my_first_model(data)
+           mean ~ Normal(0, 1)
+           sd ~ Exponential(1)


HalfCauchy is a better prior than Exponential or InverseGamma. See:

On the Half-Cauchy Prior for a Global Scale Parameter
Nicholas G. Polson, James G. Scott
Bayesian Analysis
link

Thanks for the link! Changed to a truncated Cauchy now.

README.md

yebai

I added a few more comments. The prior on the variance / standard deviation parameter is a bit odd and can be improved. Users tend to pay attention to these examples, so staying with best practices is better.

AoifeHughes · 2025-06-23T08:41:00Z

README.md

+  - Variational inference using [AdvancedVI.jl](https://github.com/TuringLang/AdvancedVI.jl).
+  - Mode estimation techniques, which rely on SciML's [Optimization.jl interface](https://github.com/SciML/Optimization.jl).
+
+## Citing Turing.jl


Could we consider adding a "Papers/Research using TuringJL". Might be useful for SEO reasons + to generally give some extra confidence to new visitors to the page.

I'm going to say no to this, for a couple of reasons:

This PR has dragged on for quite long. (Sure, it's partly me being slow, but also there have been a ton of comments on this.) This doesn't strike me as something that's necessary for this PR (i.e., we cannot merge without this), but rather a nice improvement to have. Thus, I would suggest that this be part of a separate PR.

There are probably at least a hundred papers that use Turing. I don't want to either list all of them, or pick a handful with the concomitant risk of making it seem like we endorse specific applications.

Couldn't you just put a "cited by" link? https://scholar.google.com/scholar?cites=2146088944996922757&as_sdt=2005&sciodt=0,5&hl=en something like this? I still think it's nice to see on repos

penelopeysm · 2025-07-03T15:46:28Z

@yebai, I think I've addressed your comments; are you happy with it in its current state?

yebai

Thanks @penelopeysm -- happy with the changes.

github-actions bot assigned penelopeysm Jun 3, 2025

penelopeysm force-pushed the py/readme branch 9 times, most recently from b0af4f4 to 7cbd501 Compare June 3, 2025 12:25

penelopeysm requested a review from mhauru June 3, 2025 12:27

[no ci] Rework README

f26c153

penelopeysm force-pushed the py/readme branch from 7cbd501 to f26c153 Compare June 3, 2025 12:29

penelopeysm changed the title ~~Rework README~~ Modernise README Jun 3, 2025

mhauru reviewed Jun 5, 2025

View reviewed changes

README.md Show resolved Hide resolved

README.md Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

mhauru requested review from yebai and AoifeHughes June 5, 2025 08:58

AoifeHughes reviewed Jun 5, 2025

View reviewed changes

penelopeysm added 2 commits June 16, 2025 16:23

Re-add badges

355727e

[no ci] fix badges

645e10a

penelopeysm force-pushed the py/readme branch from 7faffc0 to 645e10a Compare June 16, 2025 15:28

penelopeysm added 2 commits June 16, 2025 16:38

[no ci] have more strongly worded discouragement for discussions

cc19de2

Merge branch 'main' into py/readme

6949ac1

penelopeysm requested review from mhauru and AoifeHughes June 16, 2025 15:40

[no ci] add papers and bibtex

017abdd

penelopeysm force-pushed the py/readme branch from 4276d7d to 017abdd Compare June 16, 2025 15:48

[no ci] add section on what's changed recently

3fcda66

mhauru approved these changes Jun 16, 2025

View reviewed changes

Add getting started section

c617662

penelopeysm mentioned this pull request Jun 20, 2025

Automate formatter on PRs #2596

Closed

yebai reviewed Jun 20, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

yebai reviewed Jun 20, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

yebai reviewed Jun 20, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

yebai reviewed Jun 20, 2025

View reviewed changes

AoifeHughes reviewed Jun 23, 2025

View reviewed changes

penelopeysm added 2 commits July 3, 2025 16:42

Implement review suggestions

a5a5203

Merge branch 'main' into py/readme

1f575ac

penelopeysm requested a review from yebai July 3, 2025 15:46

yebai approved these changes Jul 3, 2025

View reviewed changes

Add Google Scholar cited-by link

f38201a

penelopeysm merged commit af3d143 into main Jul 5, 2025
30 checks passed

penelopeysm deleted the py/readme branch July 5, 2025 23:28


		Turing's home page, with links to everything you'll need to use Turing, is available at:
		https://turinglang.org contains the documentation for the broader TuringLang ecosystem.

Modernise README #2575

Modernise README #2575

Conversation

penelopeysm commented Jun 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jun 3, 2025

Uh oh!

mhauru left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mhauru commented Jun 5, 2025

Uh oh!

yebai commented Jun 5, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

penelopeysm commented Jun 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coveralls commented Jun 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 16093044479

Warning: This coverage report may be inaccurate.

Details

💛 - Coveralls

Uh oh!

codecov bot commented Jun 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

AoifeHughes commented Jun 16, 2025

Uh oh!

penelopeysm commented Jun 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yebai left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

penelopeysm Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

penelopeysm commented Jul 3, 2025

Uh oh!

yebai left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

penelopeysm commented Jun 3, 2025 •

edited

Loading

penelopeysm commented Jun 16, 2025 •

edited

Loading

coveralls commented Jun 16, 2025 •

edited

Loading

codecov bot commented Jun 16, 2025 •

edited

Loading

penelopeysm Jul 3, 2025 •

edited

Loading