Updates in the README #2750

rjlanari · 2024-08-21T08:25:08Z

Tasks

PR name contains story or task reference
Documentation (docs and inline)
Tests (including n+1 and django_assert_num_queries where applicable)
Changelog

m4ra

Thank you Ricardo! Few extra things are needed to make it a bit more specific.

README.md

m4ra · 2024-08-21T08:32:16Z

README.md

@@ -13,17 +13,18 @@ adhocracy+ is designed to make online participation easy and accessible to every

 ### Requirements

- * nodejs (+ npm)
+ * nodejs (+ npm) (Use Homebrew to reinstall the node in the projects folder runnign: brew install node)


here good to note that for MacOS it needs homebrew for installing node.
make install will take care to install the npm packages for the project, so no need to write down the reinstallation.

I took it out! thanks!

m4ra · 2024-08-21T08:34:54Z

README.md

@@ -40,7 +41,7 @@ adhocracy+ is designed to make online participation easy and accessible to every

 ### Use postgresql database for testing

-run the following command once:
+To use postgresql database in production run the following command once:


the header for this section indicates is for using postgresql for testing, so should say as the original. some developers prefer to use postgresq instead of sqlite3, me included.

Ok I leave that out!

m4ra · 2024-08-21T08:44:49Z

README.md

 - the celery config parameter "always eager" is disabled (add `CELERY_TASK_ALWAYS_EAGER = False` to your `local.py`)
+    To find local.py run: find . -name "local.py"


there is no local.py when installing from the repo. We need to create it under adhocracy_plus/config/settings.
Nice to add that the local.py can also have other customised settings such as a postgresql database setting for development.

Also would be good to point here that the celery always eager is disabled so that tests can run the celery tasks from the code that is calling them rather than scheduling them with the redis broker.

And we could end this celery section by pointing to our extensive celery documentation.
on line 79 below.

I'll make the changes as you point out!

thanks. once you make and push your changes, click the refresh button next to my reviewer name

there is a typo now schedulingmac

remove the line To find local.py run: find . -name "local.py".
Instead add: local.py sould be under adhocracy_plus/config/settings, create one if it doesn't exist. This file saves settings for local development.

m4ra · 2024-08-21T14:20:55Z

README.md

 * python 3.x (+ venv + pip)
 * libpq (only if postgres should be used)
 * sqlite3 [with JSON1 enabled](https://code.djangoproject.com/wiki/JSON1Extension)
 * redis (in production, not needed for development)
+ * pillow-heif (required for macos M1 ...etc)


By ...etc I meant what you had there already ;)

@rjlanari see my latest comment above.

m4ra · 2024-08-21T14:21:42Z

README.md

 - the celery config parameter "always eager" is disabled (add `CELERY_TASK_ALWAYS_EAGER = False` to your `local.py`)
+    To find local.py run: find . -name "local.py"


there is a typo now schedulingmac

m4ra · 2024-08-21T14:25:51Z

README.md

 - the celery config parameter "always eager" is disabled (add `CELERY_TASK_ALWAYS_EAGER = False` to your `local.py`)
+    To find local.py run: find . -name "local.py"


remove the line To find local.py run: find . -name "local.py".
Instead add: local.py sould be under adhocracy_plus/config/settings, create one if it doesn't exist. This file saves settings for local development.

goapunk · 2024-08-22T08:46:56Z

more a general suggestion but maybe it would be nice to move the postgresql and celery part into a separate section (idk, something like advanced or optional) to make clear that they are not required to develop/test a+. We could also split the setup up into a mac and a linux section to make it easier to find the relevant requirement for your platform. These are just ideas though :)

rjlanari · 2024-08-22T10:38:18Z

Thanks @m4ra for the corrections. I will put them in the file!
@goapunk, I thought of moving the postgresql and celery parts in a new section at the bottom of the file under a "Advance settings".
We can think of splitting the installations guide in macOS and Linux but I would need to know exactly what is needed for linux as I don't have it.
Let me know what you think!

m4ra

@rjlanari I have left comments that have not been addressed yet. thank you

m4ra · 2024-08-26T13:32:41Z

README.md

 * python 3.x (+ venv + pip)
 * libpq (only if postgres should be used)
 * sqlite3 [with JSON1 enabled](https://code.djangoproject.com/wiki/JSON1Extension)
 * redis (in production, not needed for development)
+ * pillow-heif (required for macos M1 ...etc)


@rjlanari see my latest comment above.

m4ra · 2024-08-26T13:35:43Z

@rjlanari

@goapunk, I thought of moving the postgresql and celery parts in a new section at the bottom of the file under a "Advance settings".

I agree with the above. However splitting the installation in Linux and MacOS not necessary I find.

m4ra · 2024-08-27T07:45:20Z

README.md

@@ -57,7 +73,10 @@ Go to http://localhost:8004/ and login with [email protected] | password



line 70 needs to go in the section Start a local server under line 40.

m4ra · 2024-08-27T07:53:55Z

README.md

 - the celery config parameter "always eager" is disabled (add `CELERY_TASK_ALWAYS_EAGER = False` to your `local.py`)
+    (Celery's always_eager is disabled to ensure tests run tasks when calling code instead of scheduling them via the Redis broker.)


hmm somehow doesn't read right the when calling code, I had suggested something different, but to be more brief, rephrase it as following:
Celery's always_eager is disabled to ensure tests run the celery tasks inline instead of scheduling them via the Redis broker.

m4ra · 2024-08-27T08:03:55Z

changelog/7978.md

@@ -0,0 +1,3 @@
+### Changes in the README
+
+I added to the readme some notes and new comands that helped me with the installation of the a+ repository locally.  


we don't use personal pronouns in the changelog, it needs to be neutral writing.
we are following this format : https://keepachangelog.com/en/1.1.0/
Titles can be:

Added for new features. Changed for changes in existing functionality. Deprecated for soon-to-be removed features. Removed for now removed features. Fixed for any bug fixes. Security in case of vulnerabilities.

So the changelog would be more like the following:

### Changed - Update README with some notes and new comands for the installation of the a+ repository locally.

m4ra · 2024-08-27T13:32:16Z

README.md

+We care about security. So, if you find any issues concerning security, please send us an email at info [at] liqd [dot] net.
+
+
+## Advance settings 


@rjlanari a typo here. should be Advanced settings

…ith best practices.

m4ra

few more things!

m4ra · 2024-08-27T14:09:52Z

README.md

@@ -13,17 +13,18 @@ adhocracy+ is designed to make online participation easy and accessible to every

 ### Requirements



Since we are revisiting the README, we can also add the tech docs.
On line 3 please add a link to our technical documentation.
E.g The project's technical documentation is in progress. You are welcome to leave your feedback on the documentation by creating a github issue.

m4ra · 2024-08-27T14:13:44Z

README.md

@@ -37,6 +38,22 @@ adhocracy+ is designed to make online participation easy and accessible to every
 ### Start a local server

    make watch
+    Go to http://localhost:8004/ and login with [email protected] | password


above line should be outside the code block, see original:

hmm this is still inside the code block @rjlanari

m4ra · 2024-08-27T14:14:23Z

changelog/7978.md

@@ -0,0 +1,3 @@
+### Changed 
+
+-  Update README with some notes and new comands for the installation of the a+ repository locally. 


typo: commands

m4ra · 2024-08-28T09:09:05Z

README.md

@@ -1,5 +1,6 @@
 # adhocracy+

+The project's [technical documentation] (https://liqd.github.io/adhocracy-plus/) currently is in progress. You are welcome to provide feedback by creating a GitHub issue..


@rjlanari has to go just after the introduction of what is aplus. When I wrote on line 3 I meant that can continue the line. sorry that was not clear enough

m4ra

two last things :)

m4ra · 2024-08-28T09:13:26Z

README.md

@@ -37,6 +38,22 @@ adhocracy+ is designed to make online participation easy and accessible to every
 ### Start a local server

    make watch
+    Go to http://localhost:8004/ and login with [email protected] | password


hmm this is still inside the code block @rjlanari

m4ra

one typo

m4ra · 2024-08-28T09:51:41Z

README.md

@@ -1,7 +1,6 @@
 # adhocracy+

-The project's [technical documentation] (https://liqd.github.io/adhocracy-plus/) currently is in progress. You are welcome to provide feedback by creating a GitHub issue..
-[adhocracy.plus](https://adhocracy.plus/) is a free Open-Source participation platform maintained and primarily developed by Liquid Democracy e.V.. It is based on [adhocracy 4](https://github.com/liqd/adhocracy4) and [Django](https://github.com/django/django).
+[adhocracy.plus](https://adhocracy.plus/) is a free Open-Source participation platform maintained and primarily developed by Liquid Democracy e.V.. It is based on [adhocracy 4](https://github.com/liqd/adhocracy4) and [Django](https://github.com/django/django). The project's [technical documentation] (https://liqd.github.io/adhocracy-plus/) currently is in progress. You are welcome to provide feedback by creating a GitHub issue.


@rjlanari there is an extra space between[ technical documentation] and the relevant link, so the markdown isn't rendering

yes! I noticed it when I saw the document! I corrected and also corrected the command blocks!

m4ra

thank you!

Updates in the README

51448a0

rjlanari requested review from goapunk and m4ra August 21, 2024 08:25

m4ra reviewed Aug 21, 2024

View reviewed changes

New updates on README.md

9de8e48

rjlanari requested a review from m4ra August 21, 2024 14:05

m4ra reviewed Aug 21, 2024

View reviewed changes

m4ra requested changes Aug 21, 2024

View reviewed changes

rjlanari requested a review from m4ra August 22, 2024 10:52

m4ra requested changes Aug 26, 2024

View reviewed changes

Latest changes in README

4159141

rjlanari requested a review from m4ra August 27, 2024 07:25

m4ra requested changes Aug 27, 2024

View reviewed changes

m4ra reviewed Aug 27, 2024

View reviewed changes

Corrected typos in README and corrected cahngelog 7978.md to comply w…

1788d1c

…ith best practices.

rjlanari requested a review from m4ra August 27, 2024 13:54

m4ra requested changes Aug 27, 2024

View reviewed changes

Updates in the README and added link to technical documentation

9c94cd9

rjlanari requested a review from m4ra August 27, 2024 15:16

m4ra reviewed Aug 28, 2024

View reviewed changes

m4ra requested changes Aug 28, 2024

View reviewed changes

README latest adjustments

faaa7d2

m4ra requested changes Aug 28, 2024

View reviewed changes

Updates README with better layout

ac0e741

rjlanari requested a review from m4ra August 28, 2024 10:03

m4ra approved these changes Aug 28, 2024

View reviewed changes

m4ra merged commit 3a67248 into main Aug 28, 2024
3 checks passed

m4ra deleted the rl-2024-08-README-updates branch August 28, 2024 10:32

		- the celery config parameter "always eager" is disabled (add `CELERY_TASK_ALWAYS_EAGER = False` to your `local.py`)
		To find local.py run: find . -name "local.py"

		@@ -57,7 +73,10 @@ Go to http://localhost:8004/ and login with [email protected] \| password

		- the celery config parameter "always eager" is disabled (add `CELERY_TASK_ALWAYS_EAGER = False` to your `local.py`)
		(Celery's always_eager is disabled to ensure tests run tasks when calling code instead of scheduling them via the Redis broker.)

		@@ -0,0 +1,3 @@
		### Changes in the README

		I added to the readme some notes and new comands that helped me with the installation of the a+ repository locally.

		We care about security. So, if you find any issues concerning security, please send us an email at info [at] liqd [dot] net.


		## Advance settings

		@@ -13,17 +13,18 @@ adhocracy+ is designed to make online participation easy and accessible to every

		### Requirements

		@@ -0,0 +1,3 @@
		### Changed

		- Update README with some notes and new comands for the installation of the a+ repository locally.

		@@ -1,5 +1,6 @@
		# adhocracy+

		The project's [technical documentation] (https://liqd.github.io/adhocracy-plus/) currently is in progress. You are welcome to provide feedback by creating a GitHub issue..

Updates in the README #2750

Updates in the README #2750

Conversation

rjlanari commented Aug 21, 2024 • edited Loading

m4ra left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

goapunk commented Aug 22, 2024

rjlanari commented Aug 22, 2024

m4ra left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m4ra commented Aug 26, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m4ra left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m4ra Aug 28, 2024 • edited Loading

Choose a reason for hiding this comment

m4ra left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m4ra left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m4ra left a comment

Choose a reason for hiding this comment

rjlanari commented Aug 21, 2024 •

edited

Loading

m4ra Aug 28, 2024 •

edited

Loading