You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@dolphinscheduler.apache.org by Jiajie Zhong <zh...@hotmail.com> on 2021/09/06 06:37:51 UTC
[PROPOSAL] Combine docs and code repo into apache/dolphinscheduler
Hi guys,
I found out we separate our code repo and docs repo into two different repo:
https://github.com/apache/dolphinscheduler-website <https://github.com/apache/dolphinscheduler-website> and https://github.com/apache/dolphinscheduler <https://github.com/apache/dolphinscheduler>.
I don’t know the original reason, but IMO we should combine the docs and codebase into same repo.
It is have several advantageous as below:
* when we change our behavior, we could modify related doc to keep our doc up to date
* when we release our code we could also release our doc, (docs follow our code), could make our doc versionable
* when adding a tag for specific commit, docs would include with it(base on first point)
So, I proposal we could combine docs into codebase repo
And here are some of other Apache repo which codebase including docs
* Apache Spark: https://github.com/apache/spark/tree/master/docs <https://github.com/apache/spark>
* Apache Flink: https://github.com/apache/flink/tree/master/docs/content/docs <https://github.com/apache/flink/tree/master/docs/content/docs>
BTW, we could still keep https://github.com/apache/dolphinscheduler-website <https://github.com/apache/dolphinscheduler-website> repo and make it just an site
for our leading page
Best Wish
— Jiajie
Re: [PROPOSAL] Combine docs and code repo into apache/dolphinscheduler
Posted by Lidong Dai <li...@apache.org>.
this is a good idea, doc should be added when the PR is ready to merge
Best Regards
---------------
Apache DolphinScheduler PMC Chair
LidongDai
lidongdai@apache.org
Linkedin: https://www.linkedin.com/in/dailidong
Twitter: @WorkflowEasy <https://twitter.com/WorkflowEasy>
---------------
On Sat, Oct 9, 2021 at 11:28 AM Jiajie Zhong <zh...@apache.org> wrote:
> Hi Calvin,
> I agrees with you about we should add a labels to mark PR, which mean
> code change PR would merge until doc PR was merged. Or maybe create a
> related doc issues Immediately.
> If you worry about lose our contributors contact, maybe the second way
> is a better choose.
>
> On 2021/09/09 06:37:47, CalvinKirs <ac...@163.com> wrote:
> > Contributors are usually required to provide relevant documents after
> submitting the code and merge. Some contributors (especially new
> contributors) may forget to provide, so contributors from the community are
> required to contribute.
> >
> >
> > Maybe we can mark it as ready merge-wait for doc after approval. At this
> time, the pr of the document is required, but some cases may cause code
> conflicts when completing the doc. There are also worse cases where
> contributors lose contact.
> >
> >
> > do you have any good suggestions?
>
>
Re: [PROPOSAL] Combine docs and code repo into apache/dolphinscheduler
Posted by Jiajie Zhong <zh...@apache.org>.
Hi Calvin,
I agrees with you about we should add a labels to mark PR, which mean code change PR would merge until doc PR was merged. Or maybe create a related doc issues Immediately.
If you worry about lose our contributors contact, maybe the second way is a better choose.
On 2021/09/09 06:37:47, CalvinKirs <ac...@163.com> wrote:
> Contributors are usually required to provide relevant documents after submitting the code and merge. Some contributors (especially new contributors) may forget to provide, so contributors from the community are required to contribute.
>
>
> Maybe we can mark it as ready merge-wait for doc after approval. At this time, the pr of the document is required, but some cases may cause code conflicts when completing the doc. There are also worse cases where contributors lose contact.
>
>
> do you have any good suggestions?
Re: [PROPOSAL] Combine docs and code repo into
apache/dolphinscheduler
Posted by CalvinKirs <ac...@163.com>.
Contributors are usually required to provide relevant documents after submitting the code and merge. Some contributors (especially new contributors) may forget to provide, so contributors from the community are required to contribute.
Maybe we can mark it as ready merge-wait for doc after approval. At this time, the pr of the document is required, but some cases may cause code conflicts when completing the doc. There are also worse cases where contributors lose contact.
do you have any good suggestions?
Best Wishes！
CalvinKirs, Apache DolphinScheduler PMC
On 09/9/2021 11:42，Jiajie Zhong<zh...@apache.org> wrote：
I agree with our release tarball would small when separate code and doc.
On the other side, contributors have to submit two PR to two repo, if some of
them forgot about adding doc, our doc would out of date.
How did we handle this problem?
Re: [PROPOSAL] Combine docs and code repo into apache/dolphinscheduler
Posted by Jiajie Zhong <zh...@apache.org>.
I agree with our release tarball would small when separate code and doc.
On the other side, contributors have to submit two PR to two repo, if some of
them forgot about adding doc, our doc would out of date.
How did we handle this problem?
Re:[PROPOSAL] Combine docs and code repo into
apache/dolphinscheduler
Posted by CalvinKirs <ac...@163.com>.
Hi:
I think it might be better to separate.
The current document is following the version, you can refer to this[1]
We will update synchronously every time we release. When new features are submitted, contributors also need to submit documents after merging the code.
I suggest keeping the documentation and the code separate so that it is more clear. For me, if there is a document, I will go to the official website to view the document online, just open the browser, instead of opening the code repository, and then look for it, Corresponding documents. That is too inefficient for me.
Similarly, we can also ensure that the source code package or binary package will not be too large when releasing, which is more convenient for users to download.
The related PR changes can be described similarly to SkyWalking by adding change.md[1], so that during the release, the documents can be checked for omissions, and users can quickly check the version changes after downloading.
[1]https://dolphinscheduler.apache.org/en-us/docs/
[2]https://github.com/apache/skywalking/blob/5.x/CHANGES.md
Best Wishes！
CalvinKirs, Apache DolphinScheduler PMC
On 09/6/2021 14:37，Jiajie Zhong<zh...@hotmail.com> wrote：
Hi guys,
I found out we separate our code repo and docs repo into two different repo:
https://github.com/apache/dolphinscheduler-website <https://github.com/apache/dolphinscheduler-website> and https://github.com/apache/dolphinscheduler <https://github.com/apache/dolphinscheduler>.
I don’t know the original reason, but IMO we should combine the docs and codebase into same repo.
It is have several advantageous as below:
* when we change our behavior, we could modify related doc to keep our doc up to date
* when we release our code we could also release our doc, (docs follow our code), could make our doc versionable
* when adding a tag for specific commit, docs would include with it(base on first point)
So, I proposal we could combine docs into codebase repo
And here are some of other Apache repo which codebase including docs
* Apache Spark: https://github.com/apache/spark/tree/master/docs <https://github.com/apache/spark>
* Apache Flink: https://github.com/apache/flink/tree/master/docs/content/docs <https://github.com/apache/flink/tree/master/docs/content/docs>
BTW, we could still keep https://github.com/apache/dolphinscheduler-website <https://github.com/apache/dolphinscheduler-website> repo and make it just an site
for our leading page
Best Wish
— Jiajie