Yes, the issue title is intentionally vague so that we can develop this as your learn, Ayman :), but I'm creating this so that you've something you can work on tomorrow (Oct 9) for your October detour into this project.
We'd like you to use this initial issue as a learning opportunity, rather than just something to tick off and do. I'll try to outline how I approach a new project below, stepping you through my process, but you do it your way - the key thing is to focus on making the most of the learning opportunity.
Project background
Stating the obvious, but always start by reading the project README.md - it's a chance not only to learn an overview of the project but also it often gives you a chance to contribute something back - you've got fresh eyes that may notice inconsistencies or things that don't work for a new person.
There's a lot to take in there in the README, but follow the instructions to clone the repository see that it runs as expected. I did this myself yesterday and found an issue (could be specific to my setup), which I documented in an issue as a first contribution (helping me learn and contributing to the project). In that case, it was something I could fix myself, but that's not usually the case with a project that is new to me.
After your initial clone and test, it's time to dig a bit deeper. Now I've asked a lot of questions below - these aren't to be answered, but rather just to get you thinking and hopefully curious to learn. Take a look at some of the technologies which the README talks about, for example:
Keycloak - read a little about keycloak and the problem it solves, or read an LLM summary - whatever works for you. Understand a little about what keycloak is solving in the system (don't settle simply for "authentication" - it's an opportunity to learn).
MinIO - Amazon AWS S3 compatible storage - see what you can learn by reading a bit about the history of MinIO, why it exists. How is it similar and how is it different to AWS's S3 service? Why is MinIO being used in this project ?
Don't worry if it's all new information (or if it's all info you already understand) - the aim is just to get an overview so we can fill in gaps later where we need to. In your case, you'll be focusing on the Python API soon, so just look at this as a chance to get the bigger picture, even if it's not complete.
Once you've worked through the README, take a look at the docs directory and note that there's two that stand out which are worth reading through:
Though, taking a look at the docs directory on GitHub shows that there has been more recent updates to the docs which are relevant, but those two docs haven't been updated... can you see what the recent changes were and why they're relevant to those two docs (GH conveniently shows you the latest commit message for each file)? It probably requires more project knowledge than you or I have to fix that inconsistency reliably (ie. not just asking an LLM to fix it), but it could be an opportunity to create your first issue for the project, just outlining the inconsistency so it is addressed by someone. On a more general note for these docs, I'd like to double-check with @monkeypants , but I'm guessing a lot of the doc directory is LLM generated and modified without enough human editing to trim it down to something reasonable to read (I certainly didn't continue reading at that point, and postponed it to later).
The Python API
Enough of docs! Let's move on to get our hands dirty with the actual Python API we'll be focusing on.
First, re-run the dev environment as per the README, login as an admin (in the dev env. admin/password) or otherwise, open the developer console of your browser, then see if you can upload a file and watch for the requests going to the API in the browser's request console. Playing around and watching requests is a great way to see where the API is being used and matching that to what we've read.
Next, verify that you can run the existing tests for the api component and that they all pass. Note: At this point in my own learning of the project - I'm new to STUF too - I tried running tests but that failed as I documented in #36 and fixed in #37, another small contribution to make it easier for the next person, hopefully.
A key thing you may notice is that this python API is using FastAPI - a python library. It is worthwhile, at this point, learning a bit about FastAPI itself too - I often choose to go off and browse the project docs, setup and test a small project of my own, before coming back to continue... I need to understand the framework/library being used before I can expect to understand what I'm doing (or even understand what an LLM recommends).
There's a document there in the api directory with the name fixme.org, which has a bunch of tasks that need fixing, some of which are done, some of which are not - it may be a great place to start and find one which isn't done and that isn't too complicated, such as the DEFAULT_BUCKET one. But again, if you choose one, use it as a learning opportunity - what the pros and cons are of different strategies, understand your options, find out the best way to test the change etc. etc.
I suspect some of the fixme.org issues will be the best place to start, though there's also #24 which is related (though may require more specific learning again). Don't be afraid to create issues for things that you see, nor ask questions as you go - either here on GH or in the slack channel we created, so that any of us can respond. We'll try to respond ASAP. I hope you've got a few things to keep you going for the next few days.
Most of all (to sound like a broken record, I'm sure), make the most of the learning opportunity :)
Yes, the issue title is intentionally vague so that we can develop this as your learn, Ayman :), but I'm creating this so that you've something you can work on tomorrow (Oct 9) for your October detour into this project.
We'd like you to use this initial issue as a learning opportunity, rather than just something to tick off and do. I'll try to outline how I approach a new project below, stepping you through my process, but you do it your way - the key thing is to focus on making the most of the learning opportunity.
Project background
Stating the obvious, but always start by reading the project README.md - it's a chance not only to learn an overview of the project but also it often gives you a chance to contribute something back - you've got fresh eyes that may notice inconsistencies or things that don't work for a new person.
There's a lot to take in there in the README, but follow the instructions to clone the repository see that it runs as expected. I did this myself yesterday and found an issue (could be specific to my setup), which I documented in an issue as a first contribution (helping me learn and contributing to the project). In that case, it was something I could fix myself, but that's not usually the case with a project that is new to me.
After your initial clone and test, it's time to dig a bit deeper. Now I've asked a lot of questions below - these aren't to be answered, but rather just to get you thinking and hopefully curious to learn. Take a look at some of the technologies which the README talks about, for example:
Keycloak - read a little about keycloak and the problem it solves, or read an LLM summary - whatever works for you. Understand a little about what keycloak is solving in the system (don't settle simply for "authentication" - it's an opportunity to learn).
MinIO - Amazon AWS S3 compatible storage - see what you can learn by reading a bit about the history of MinIO, why it exists. How is it similar and how is it different to AWS's S3 service? Why is MinIO being used in this project ?
Don't worry if it's all new information (or if it's all info you already understand) - the aim is just to get an overview so we can fill in gaps later where we need to. In your case, you'll be focusing on the Python API soon, so just look at this as a chance to get the bigger picture, even if it's not complete.
Once you've worked through the README, take a look at the docs directory and note that there's two that stand out which are worth reading through:
Though, taking a look at the docs directory on GitHub shows that there has been more recent updates to the docs which are relevant, but those two docs haven't been updated... can you see what the recent changes were and why they're relevant to those two docs (GH conveniently shows you the latest commit message for each file)? It probably requires more project knowledge than you or I have to fix that inconsistency reliably (ie. not just asking an LLM to fix it), but it could be an opportunity to create your first issue for the project, just outlining the inconsistency so it is addressed by someone. On a more general note for these docs, I'd like to double-check with @monkeypants , but I'm guessing a lot of the doc directory is LLM generated and modified without enough human editing to trim it down to something reasonable to read (I certainly didn't continue reading at that point, and postponed it to later).
The Python API
Enough of docs! Let's move on to get our hands dirty with the actual Python API we'll be focusing on.
First, re-run the dev environment as per the README, login as an admin (in the dev env. admin/password) or otherwise, open the developer console of your browser, then see if you can upload a file and watch for the requests going to the API in the browser's request console. Playing around and watching requests is a great way to see where the API is being used and matching that to what we've read.
Next, verify that you can run the existing tests for the api component and that they all pass. Note: At this point in my own learning of the project - I'm new to STUF too - I tried running tests but that failed as I documented in #36 and fixed in #37, another small contribution to make it easier for the next person, hopefully.
A key thing you may notice is that this python API is using FastAPI - a python library. It is worthwhile, at this point, learning a bit about FastAPI itself too - I often choose to go off and browse the project docs, setup and test a small project of my own, before coming back to continue... I need to understand the framework/library being used before I can expect to understand what I'm doing (or even understand what an LLM recommends).
There's a document there in the api directory with the name fixme.org, which has a bunch of tasks that need fixing, some of which are done, some of which are not - it may be a great place to start and find one which isn't done and that isn't too complicated, such as the
DEFAULT_BUCKETone. But again, if you choose one, use it as a learning opportunity - what the pros and cons are of different strategies, understand your options, find out the best way to test the change etc. etc.I suspect some of the fixme.org issues will be the best place to start, though there's also #24 which is related (though may require more specific learning again). Don't be afraid to create issues for things that you see, nor ask questions as you go - either here on GH or in the slack channel we created, so that any of us can respond. We'll try to respond ASAP. I hope you've got a few things to keep you going for the next few days.
Most of all (to sound like a broken record, I'm sure), make the most of the learning opportunity :)