-
-
Notifications
You must be signed in to change notification settings - Fork 360
Schema image / ER Diagram is out of date #54
Comments
My recommendation would be to (in order of preference):
|
@bernhard-hofmann Please check the reference if you are talking about something like this: DEMO Link: https://app.sqldbm.com/PostgreSQL/Share/D2_vEBIrEiAJR9khhTwB-EGFrngIE8md_DYjF4jNYw0 **Pricing: 1 active project in your Free plan ** If yes, then i can take initiative to complete this task! |
@Dhara159: Seems the free plan comes with max. 3 revisions. I don't think it would be a good idea to go with it. As @bernhard-hofmann mentioned, It would be helpful to give a date along with the filename to maintain the revisions |
Also, given that Chapter has now been decided to be a self-hosted solution I'm not sure this schema makes 100% sense any more, especially if there is no "central" service for keeping track of all users/groups/events across all instances. And honestly if it's self hosted by individual orgs/groups postgres might even be overkill and sqlite might be a simpler alternative. |
@kognise also has a proposed "terminology" update to the readme to call a "chapter" effectively what a "group" is in the schema. Group is pretty vague and it would be nice to have some parity between the core item in the schema and what we're referring to in the business logic terminology. So, can we change "groups" to "chapters"? |
@nik-john is changing "group(s)" to "chapter(s)", so when this get's updated then please reflect those changes in the schema image. |
Sorry to ask, but can we bring this issue back on topic? I'd really like a schema diagram; I find them very useful to understand the schema without having to create the image in my head from SQL text. But how are we going to ensure it's kept up to date without relying on one person to re-create it whenever someone updates the SQL? I'll have a look at DBeaver and PGAdmin, thanks @dmmulroy. Maybe we can include steps asking that PRs that update the SQL include an updated schema image? |
I think requesting an updated schema image is a reasonable request, esp. if DBeaver and PGAdmin diagrams are acceptable. |
@dmmulroy I think an up to date image from tool X is better than an outdated one from DataGrip, so if you can generate a new image and to a PR then I suspect folks will like it. Also, #46 is merged in so a lot has changed on the ddl.sql. #72 Also, if we changed the readme to link to |
Also, #70 used dbdiagram.io to generate a diagram, but it's also outdated. |
@francocorreasosa I was able to generate a new ER Diagram using the dbdiagram.io. Though, the PostgreSQL import feature doesn't recognize timestamptz field types, so I had to manually work around it. What's the best way to add the new diagram.png? I'm assuming creating my own new pull request, but I wanted to confirm there's not a trick to piggybacking on your existing #70. |
I would recommend using DBeaver for making new ER diagrams. Have a look here: #70 (comment) |
I do like the icons in the DBeaver more than the dbdiagrams.io version. So, I'm on board with that one if other have the same preference. |
Anybody have a problem with the eventual PR for the updated schema image also linking directly to the raw https://github.com/freeCodeCamp/chapter/raw/master/data/schema.png |
A pull request with updates to the DDL.SQL file must include an updated image of the schema. I'm closing this issue with the above assumptions. |
#129 brought in an up to date schema image and we're now linking the readme directly, but through an absolute path to https://github.com/freeCodeCamp/chapter/raw/master/data/schema.png So, we should explore now linking to the path relative to the repo and branch, since otherwise any forks or branches would always see the upstream master branch's copy of the image, and not any locally modified versions. A small concern, but one that could easily confuse someone how updates the schema on their fork and then looks at their README and still sees the upstream master version. Is this as simple as doing src="data/schema.png" ? |
#130 merged in a relative Github's Markdown is smart enough to convert that relative path to a path for the active repo and branch. This is working on the main master repo and my fork and was approved and merged. |
@dmmulroy @bernhard-hofmann we have schema changes and I wondered if you can let us know if / how the ddl.sql was being generated. With a tool, or manually? Also, we're going to need to generate a new schema.png and I don't have the database installed locally so DBeaver wouldn't allow me to just generate a diagram without a real database. Any help on this stuff? |
I'm all for the automation part of it, even we lose the ability to drop one-large image into the repo. @Zeko369 with hosting this on GH pages, would the generated files be pushed into this repo, or would we have to host it on a dedicated repo? |
Hmm good question, we could host the whole thing on |
Took me a while to find the diagram you referred to as "Large" view. This is the link for my fellow hunters: https://schemaspy.now.sh/relationships.html. I wonder if the direct image link updates so that we could link directly to this: https://schemaspy.now.sh/diagrams/summary/relationships.real.large.png |
It does, but I wanted an offline option, so only keep the large in the repo. Also could you please remove the image from the latest comment or make it a collapsible because like this these 2 images are like half the comments in size hahah |
@Zeko369 @bernhard-hofmann with the recent PRs dealing with models for the schema changes I was reminded the schema.png is out of date. Here, we discussed the possibility of generating both a basic schema image and interactive schemaspy pages. @Zeko369 mentioned GitHub pages and it seems you can set the /docs directory of a master branch to be hosted by GitHub pages. The screenshot here is from my repo, but it looks like I have access to enable it for this repo and the URL would become https://freecodecamp.github.io/chapter/ #362 is consolidating some documentation and removing unnecessary things from /docs. So, would we be able to have:
|
#383 had more major schema changes, so we'll want to revisit this open issue to auto-generate a schema image or schemaspy. #54 (comment) sums up our last conversation on this topic. |
@allella, tnx for reminding us. My idea on how we should procede:
The action should just build the image and make a PR to add the new image so we can check if there are any problems with it |
@Zeko369 sounds good. Is there anybody else we can think to help with this task to keep you on the MVP stuff? |
Whoever is interested can jump on this, I was thinking about making this more general so it can be used with for example prisma2 client and other similar stuff. But if anyone is interested let's start building this |
From my comment above, we're talking about turning on Github pages for this repo. Any concerns with that plan? This would allow for an auto-generated and more interactive schema, like Fran outlined above with schemaspy, but could be used for eventual docs beyond the Wiki.
@Zeko369 I'm concerned if we don't assign it to someone, then it will just sit around. @ScottBrenner do you have time and interest or know someone in the project who could help? |
@allella A side note related to online docs. |
No concerns at all. This sounds like a good idea. |
@Zeko369 this is still a to-do I'd like to move along. Is the CI building still messed up? Also, you mentioned including Schemaspy in a Docker container. It sounds like most contributors aren't using Docker, except for Windows or services like PostgreSQL. So, would we change anything about the plan above? Thanks |
As discussed above, I'd like to commit a copy of Schemaspy for use with GitHub pages (GHP). I got Schemaspy working locally and will push it in manually as needed until we get a fully automated solution. The options are to
@Zeko369 @QuincyLarson @bernhard-hofmann thoughts? |
@nhcarrigan mentioned that fCC uses docs/. My concern with using the main branch is that these SchemaSpy docs are not just text files. It includes about 14 MB of JS files and images. If we included other binary-heavy docs in the main branch or repo, then it would obviously slow down things in some situations for development and production that many not want / need those files locally. For instance, someone on a slow connection who forks the project may inherit MBs of unnecessary downloading. A docs branch or entirely separate repository would limit or avoid those issues. I'm good either way, but I didn't want to just push this into docs/ and have it bog things down. |
@vkWeb I'm thinking we should create a gh-pages branch in this repo. I'm not sure I have write permissions. I see you created a feat/search branch. How was that done? Was it because you have write permissions? |
I'm thinking we need to run
and then push that to the main repo because I'm not sure a PR can create a new branch, or that I have permissions to create a new branch if it's possible through a PR. |
Hi @allella! 😄 Yes, only people with write permissions can push a branch to chapter repo. We should not be using --orphan in our case, because it creates a new branch without any parent commit, it's like a totally new repository in itself (I got to know this by reading git's doc). I don't see any point of doing this. I have created a gh-pages branch and I've added a starter index.html to test the deployment, our documentation is successfully deployed at: https://freecodecamp.github.io/chapter/ Some helpful commands for contributing to gh-pages documentation
|
Thanks @vkWeb. I may have write permissions, but I don't see anything saying I do like on other projects where I know I have a role. The current proposal is to use this for Schemaspy and then decide if we're going to put other docs in the same place. It may be best as a supplemental place to host complex / interactive docs and then keep the standard ones README, CONTRIBUTING in the main repo where people expect to find them. For what it's worth, the "orphan" branching is suggested by Github. It doesn't really matter to me since you manually removed most of the files to achieve the same result. A separate repo would probably be an ideal solution, but for now we'll work with what we have. Thanks, |
I'm documenting how to manually run SchemaSpy since we'll likely not have this automated soon. We'll link this via CONTRIBUTING.md once the gh-pages is live. The notes below assume SchemaSpy is running in a directory called chapter-schemaspy in the same parent directory as the main chapter directory, as illustrated below.
Steps to Checkout a Clean GitHub Pages BranchCheckout a clean branch derived from the chapter/gh-pages branch. Make sure you don't have any uncommitted changes as the hard reset steps will wipe them out. Kudos to @vkWeb for these steps.
Start the Chapter application in Docker mode and check that the PostgreSQL service is running. Or, if you're running the Chapter application in Manual Mode, then check that the local PostgreSQL is running. Steps to Download and Run SchemaSpyThis assumes you have the SchemaSpy requirements satisfied, like a current Java or OpenJDK installed. Create and go to the chapter-schemaspy directory.
Download a SchemaSpy .jar file (version 6.1.0 or newer).
Download the latest supported JDBC for Postgres driver, such as
Then, in the chapter-schemaspy directory, execute SchemaSpy as follows (adjusting -jar and -dp filenames, -host, -port, -u username and such as needed)
This will generate a fresh set of SchemaSpy files in ../chapter. Verify, Commit, Push to Origin, and Create a Pull RequestGo back to the ../chapter clone and verify the the output went to the correct place and against the GitHub Pages branch you created above (gh-pages-updates in our example above).
Once the Schema files have been refreshed you can open the index.html of the gh-pages branch in your web browser and the Schemapy generated content should be displayed. If everything looks correct, commit, push your branch to your origin fork, and create a pull request against the chapter/gh-pages branch. Special Considerations
|
Docs have been updated as well via #456 . |
Not sure why this didn't auto-close with #453. Closing. |
Whilst I like the image of the schema, it's not auto-generated on updates to the SQL script so it could be misleading.
The version there is generated by a tool called DataGrip from JetBrains which is not free.
The text was updated successfully, but these errors were encountered: