Describe current project state and how to contribute #321
Conversation
|
Thanks |
| The Pekko project spans multiple Github repositories. Work required for a whole Pekko project release (multiple repositories) is tracked in the [Apache Pekko Github project](https://github.com/orgs/apache/projects/220/views/1). Note that due to Apache Software Foundation regulations, this cannot be made public and is viewable only by Apache project [committers](https://www.apache.org/foundation/how-it-works.html#committers). Therefore non-committers check up on the Github Discussions and dev mailing list to confirm contents of the current in-development release. | ||
|
|
||
|
|
||
| Repositories |
There was a problem hiding this comment.
I generally don't agree with most of the changes here and kind of think that this stuff is better driven via issues or email discussion than PRs.
I definitely don't think that the README in this Git repo is our main doc. Our main doc is https://pekko.apache.org
I have taken this 'repositories' section and included it at https://pekko.apache.org/modules.html
There was a problem hiding this comment.
While the README may not be the "main doc" it is probably the fist point of contact for many people looking for documentation. And it will be displayed on the Github page.
I also note that this pull request is a draft and I think it is a good start as it provides us with a view of exactly what is being suggested. Back when I reviewed ticket #112 I suggested that a discussion be opened on the mailing list with a "[DISCUSS]" tag. @samueleresca please start the conversation in the mailing list.
I think that we need to look at different paths to finding Pekko. Some will come in via apahce.org and simply use the library. We might call them consumers (I hate the term "users" -- that is what drug dealers have). The second group will be looking for how to contribute and will come via github. For this group the dev centered documentation should start in the README.
There was a problem hiding this comment.
If we are specifically dealing with contributing, the convention is to put a cheat sheet/quick start guide in CONTRIBUTING.md in the root git repo (this convention is also followed by github, i.e. it will pick it up and reference it when someone tries to make a PR).
Of course within that CONTRIBUTING.md you can always reference to the actuals docs which will be hosted on the main https://pekko.apache.org/ site.
There was a problem hiding this comment.
With the small team and the large number of repos - duplicated docs are turning into a real maintenance nightmare. I have no problem linking to one source of truth.
There was a problem hiding this comment.
a PR merged today has added a link to the pekko.apache.org docs
There was a problem hiding this comment.
Thanks for the feedback. Right now, there is a conversation (resumed from a past discussion) in the mailing list, see https://lists.apache.org/thread/8gnbv8g8z9fjlnlgbp903f51f3fd8634. I'm happy to reopen a thread with the "[DISCUSS]" tag. Also, I agree with the "avoid duplication" point:
- I'm proceeding by taking in the changes added yesterday to point to the actual documentation.
- I'm proceeding by removing the "Repository" section, as it would lead to duplication.
This PR is related to #112. The PR (and these changes) need to be discussed in the mailing list. Any feedback/suggestion is welcome.
Changes in
README.MD:Changes in
CONTRIBUTING.MD:Others
Branch summarysection correct? Will we use theRelease-x.y.zmaintenance branches?