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:56:58Z

README.md

+### Discussions
+
+This repository also has a [Discussions page](https://github.com/TuringLang/Turing.jl/discussions), where you can create discussions and ask questions about statistical applications and theory.
+In practice, we don't monitor this as often: you're more likely to get a response through an issue.


I'm not convinced having the discussions enabled really adds much value, and it splits similar information between two places. Would be a shame to lose the old discussions though.

I agree that discussions are better opened as issues or Julia discourse.

@mhauru I think there is a GH option to transfer discussions into issues if we want to disable it.

+1 to what @mhauru has said. Maybe move some of the below lines up. Push more to use slack for what the discussion handles and issues for anything specifically wrong or needing enhanced?

There are a few ways:

Leave as is (in which case this text can probably stay)

Move all discussions to issues and disable discussions

Transfer all discussions to a separate repo and disable discussions

Happy to go with whichever one. Personal preference is (2).

I'm happy with 1. or 2.

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.

AoifeHughes · 2025-06-05T10:01:38Z

README.md

+### Discussions
+
+This repository also has a [Discussions page](https://github.com/TuringLang/Turing.jl/discussions), where you can create discussions and ask questions about statistical applications and theory.
+In practice, we don't monitor this as often: you're more likely to get a response through an issue.


+1 to what @mhauru has said. Maybe move some of the below lines up. Push more to use slack for what the discussion handles and issues for anything specifically wrong or needing enhanced?

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 15703075136

Details

0 of 0 changed or added relevant lines in 0 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage increased (+0.07%) to 85.636%

Totals
Change from base Build 15604552633:	0.07%
Covered Lines:	1246
Relevant Lines:	1455

💛 - Coveralls

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

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 85.57%. Comparing base (8be9094) to head (c617662).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2575      +/-   ##
==========================================
+ Coverage   85.50%   85.57%   +0.06%     
==========================================
  Files          22       22              
  Lines        1456     1456              
==========================================
+ Hits         1245     1246       +1     
+ Misses        211      210       -1

☔ 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

yebai · 2025-06-20T17:33:28Z

README.md

+
+### Discussions
+
+This repository also has a [Discussions page](https://github.com/TuringLang/Turing.jl/discussions), where you can create discussions and ask questions about statistical applications and theory.


Better to remove Discussions in favour of issues / Slack / Julia Discourse.

yebai · 2025-06-20T17:36:48Z

README.md

+
+  - Markov Chain Monte Carlo (both an abstract interface: [AbstractMCMC.jl](https://github.com/TuringLang/AbstractMCMC.jl), and individual samplers, such as [AdvancedMH.jl](https://github.com/TuringLang/AdvancedMH.jl), [AdvancedHMC.jl](https://github.com/TuringLang/AdvancedHMC.jl), and more).
+  - 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).


Suggested change

- Mode estimation techniques, which rely on SciML's [Optimization.jl interface](https://github.com/SciML/Optimization.jl).

- Maximum likelihood and maximum a posteriori estimation, which rely on SciML's [Optimization.jl interface](https://github.com/SciML/Optimization.jl).

yebai · 2025-06-20T17:38:28Z

README.md

+
+There are also often threads on [Julia Discourse](https://discourse.julialang.org) (you can search using, e.g., [the `turing` tag](https://discourse.julialang.org/tag/turing)).
+
+We are most active on GitHub, but we do also keep an eye on both Slack and Discourse.


We don't need this.

Suggested change

We are most active on GitHub, but we do also keep an eye on both Slack and Discourse.

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.

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

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

Open

yebai reviewed Jun 20, 2025

View reviewed changes


		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.


		### Discussions

		This repository also has a [Discussions page](https://github.com/TuringLang/Turing.jl/discussions), where you can create discussions and ask questions about statistical applications and theory.

	- Mode estimation techniques, which rely on SciML's [Optimization.jl interface](https://github.com/SciML/Optimization.jl).
	- Maximum likelihood and maximum a posteriori estimation, which rely on SciML's [Optimization.jl interface](https://github.com/SciML/Optimization.jl).


		There are also often threads on [Julia Discourse](https://discourse.julialang.org) (you can search using, e.g., [the `turing` tag](https://discourse.julialang.org/tag/turing)).

		We are most active on GitHub, but we do also keep an eye on both Slack and Discourse.

Modernise README #2575

Are you sure you want to change the base?

Modernise README #2575

Uh oh!

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!

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!

Choose a reason for hiding this comment

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!

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 15703075136

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!

Choose a reason for hiding this comment

Uh oh!

yebai Jun 20, 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!

yebai left a comment

Choose a reason for hiding this comment

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

yebai Jun 20, 2025 •

edited

Loading