RFC 8 Reorganization of Repositories #159
Conversation
nielsleadholm
requested review from
tristanls,
scottcanoe,
vkakerbeck and
hlee9212
|
Thanks for the useful comments @vkakerbeck , have made some adjustments. |
rfcs/0007_reorganize_repositories.md
Outdated
| - Local forks of `monty_lab` can be used by contributors to track in-progress work. However, this does not mean that such code, once mature enough to be shared, should necessarily be merged into the main `monty_lab` repository. | ||
| - In general, if the code is likely to be re-used in the future, or forms part of a paper, it should *not* go in `monty_lab` (more on this below). | ||
| - Circle-CI does not include style or unit-test checks on new code. | ||
| - When merging a discontinued project, PR review does not need to be as thorough as for code pushed to the main `tbp.monty` repository. |
There was a problem hiding this comment.
thought: I think having a lesser standard for some repositories over others will be toilsome in the long run. The code standards are not there to make the code look pretty but to reduce the cognitive load of contributors and speed up our ability to change the code without breaking existing functionality. After two and a half months of its existence, I was already asked to improve the code quality of monty_lab.
There was a problem hiding this comment.
Do you mean you would prefer if we didn't have some code which we say can be of a lesser standard?
Are you referring to the review of floppy? That was specifically highlighted because it does not fit in with the other code found in monty_lab, which is why we are having this discussion to presumably move it into its own package-like repository.
The idea for having a different standard in monty_lab is that it would essentially be an archive of discontinued work.
There was a problem hiding this comment.
🤔, I think I was responding to monty_lab as it is currently being used and did not imagine it in the state described in this RFC.
suggestion: Going back through and thinking of monty_lab as outlined in the RFC, I would say that we should probably make it an archive and no longer merge code to it. If we have some future code that we want to archive, we could archive the repo that the code is in and not go through the effort of moving it over.
There was a problem hiding this comment.
Ok yeah I liked this idea, so essentially archive the current monty_lab and discontinue its use going forward. For future code that needs archiving, we can just use the archive functionality. @vkakerbeck @scottcanoe @hlee9212 @ramyamounir any objections to this?
There was a problem hiding this comment.
I'm fine with this approach.
There was a problem hiding this comment.
That's a good point Ramy about how to name these. So if we are using repository tags as you suggest @tristanls , would archived repositories (and therefore effectively all repositories) have the tbp.* prefix? If there's no issue with this, then I'll make sure this is part of the description.
There was a problem hiding this comment.
@nielsleadholm, I have no issues with tbp.* prefix for all repos, as they're likely to be Python, and we're using that to avoid PyPi name collisions.
note: There are currently exceptions, for example https://github.com/thousandbrainsproject/cla, which does not have a tbp.* prefix.
suggestion: Maybe highlight why we put the tbp.* prefix in front of things? Again, as far as I understand, we originally put the tbp.* prefix in tbp.monty because a monty project already existed on PyPi. So, this was to deconflict the name of a published package. By having our Python repositories and packages retain the tbp.* prefix, we are carving out our own namespace in the PyPi global namespace. In other contexts, this may not be necessary. For example, conda has the concept of organizations, where our prefix is thousandbrainsproject::. Other languages offer namespacing solutions as well.
There was a problem hiding this comment.
Ok yeah I liked this idea, so essentially archive the current
monty_laband discontinue its use going forward. For future code that needs archiving, we can just use the archive functionality. @vkakerbeck @scottcanoe @hlee9212 @ramyamounir any objections to this?
I know I already gave LGTM but I came back to read this portion a bit more carefully. To @nielsleadholm I am fine with this approach.
Pretty exciting how this will pan out!
There was a problem hiding this comment.
Great thanks Tristan, I'll make sure to highlight that. I believe that was while I was on PTO, so just double checking with @vkakerbeck that you have the same memory as Tristan as to the reason for the tbp.* prefix? I can update the guidance to advise that this should be used for all Python repositories.
There was a problem hiding this comment.
Yes, avoiding name collisions was the reason we added the tbp. prefix to monty. I like the idea of keeping that as a convention for other repositories, as it seems like a nice branding opportunity to clearly associate our repos and Pypi packages with this project. However, if there is a strong argument against doing this for repos without naming conflicts (for example to avoid unnecessary nesting of folders) I also don't mind not doing this.
rfcs/0007_reorganize_repositories.md
Outdated
| - If a given paper is separated into multiple repositories, will this create unecessary challenges for someone who wants to replicate the results (e.g. generating a figure)? We can think about how to structure results folders to make this as easy as possible. | ||
| - Should we be open to merging code into `monty_lab`'s `main` as a form of staging before it is eventually moved to a final repository? This would be akin to what has organically happened with the recent paper work. | ||
| - An advantage of this would be to make it easier for maintainers to review provisional code that is not yet ready for a final repository. | ||
| - What would be a good place for providing an overview of all the repositories in the codebase, with descriptions and links to them? Perhaps on https://thousandbrainsproject.readme.io/docs/ ? |
There was a problem hiding this comment.
suggestion: With helpful descriptions and tags, the built-in GitHub page can serve this purpose: https://github.com/orgs/thousandbrainsproject/repositories
There was a problem hiding this comment.
Ah, for this my thought was creating a GitHub profile README page.
It looks like above - if someone comes to our org, then they should see like a README, which can contain overview of all repositories. I think this profile README can be created by creating a repo that is the same name as the username.
The only thing is I'm not sure if it works for organizations (I have done it on personal account). @tristanls would you happen to know?
Update: If creating a new .github repo would be too much overhead (e.g. I wouldn't want to make one for 191 repos if I had that many), then I'm also totally fine with tagging and descriptions.
There was a problem hiding this comment.
Update: Yes, it is possible to add profile README to organizations - you create a .github repo and add a README file.
There was a problem hiding this comment.
The organization's README page is a good idea. I think that meets the intent better than the repositories page.
|
📚 Documentation Preview ✅ A preview of the documentation changes in this PR is available for maintainers at: Last updated: 2025-03-03 15:04 UTC |
|
Thank you everyone for your feedback on this, I'd like to now motion for final comment period (FCP). All Maintainers please indicate your final views on the RFC. To summarize the changes I have made following feedback:
|
nielsleadholm
requested review from
tristanls,
scottcanoe,
vkakerbeck,
ramyamounir,
hlee9212 and
codeallthethingz
rfcs/0000_reorganize_repositories.md
Outdated
| 1. `tbp.monty` - This is the main repository for the Monty framework. | ||
| 2. `monty_lab` - This is what `nupic.monty/projects` used to be, and is currently a catch-all for code that is not part of the main Monty framework. | ||
|
|
||
| The high-level proposal is to discontinue the use of `monty_lab` (archiving the existing repository), and instead have a very low threshold for creating new, independent repositories for different projects. |
There was a problem hiding this comment.
Is there a reason we need to archive monty_lab? At what point would we archive other repos? I'm just thinking, especially since monty_lab contains a bunch more experiment configs as well as the monty meets world app code we/other people may still want to use the code in there (and occasionally add fixes) even if we don't actively add more project folders to it.
There was a problem hiding this comment.
Yeah good point, I've updated the guidance on this. Let me know if it still isn't clear.
|
Looks good! 🏅 |
nielsleadholm
changed the title
This RFC proposes how we might reorganize our repositories to be comprehensible and maintain code quality going forward.