You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@couchdb.apache.org by GitBox <gi...@apache.org> on 2022/09/07 04:19:46 UTC
[GitHub] [couchdb] nickva opened a new pull request, #4164: Integrate docs into the main repo
nickva opened a new pull request, #4164:
URL: https://github.com/apache/couchdb/pull/4164
Related to the discussion in [dev ML](https://lists.apache.org/thread/x4lc6vhthj1vkt2xpd0ox5osh959qsc4)
The main advantage for doing it are:
* No need to create a separate PR for features. Less efforts to update docs.
* Make it easier to generate releases. Release notes track source changes.
* Speed up `./configure` as there one less dependency to fetch.
One of the objects of doing this, as discussed in the ML was that docs PRs have a lightweight CI. This PR attempts to address that with the changes to the `Jenkinsfile.pr` (thanks to @big-r81 for the idea in the ML) where the following logic is used:
* If any docs files are changed, run docs `make check` (a quick format check)
* If only docs changed, then docs `make html pdf` is run, like in the previous separate docs repo. All the other CI steps are skipped.
* If other files are changed not just docs, then the full CI is run. As part of that `make dist` also builds docs.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@couchdb.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [couchdb] big-r81 commented on pull request #4164: Integrate docs into the main repo
Posted by GitBox <gi...@apache.org>.
big-r81 commented on PR #4164:
URL: https://github.com/apache/couchdb/pull/4164#issuecomment-1242045469
Maybe it’s a good idea to define an .editorconfig for the project / projects?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@couchdb.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [couchdb] nickva commented on pull request #4164: Integrate docs into the main repo
Posted by GitBox <gi...@apache.org>.
nickva commented on PR #4164:
URL: https://github.com/apache/couchdb/pull/4164#issuecomment-1242207082
@jaydoane https://github.com/apache/couchdb/pull/4171
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@couchdb.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [couchdb] nickva commented on pull request #4164: Integrate docs into the main repo
Posted by GitBox <gi...@apache.org>.
nickva commented on PR #4164:
URL: https://github.com/apache/couchdb/pull/4164#issuecomment-1242199160
I tried this in `.emacs`:
```
'(groovy-indent-offset 2)
```
I'll reformat both the full and pr files
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@couchdb.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [couchdb] jaydoane commented on a diff in pull request #4164: Integrate docs into the main repo
Posted by GitBox <gi...@apache.org>.
jaydoane commented on code in PR #4164:
URL: https://github.com/apache/couchdb/pull/4164#discussion_r965330220
##########
src/docs/README.md:
##########
@@ -0,0 +1,31 @@
+# CouchDB Documentation
+
+This directory contains the Sphinx source for Apache CouchDB's documentation.
+You can view the latest rendered build of this content at:
+
+ http://docs.couchdb.org/en/latest
+
+# Building this repo
Review Comment:
Maybe just "Building the docs" or similar now that it's not a separate repo?
##########
build-aux/Jenkinsfile.pr:
##########
@@ -61,7 +64,68 @@ pipeline {
stages {
+ stage('Docs Check') {
+ // Run docs `make check` stage if any docs changed
+ when { expression { return sh(returnStatus: true, script: docs_changed) == 0 } }
+ agent {
+ docker {
Review Comment:
Looks like indentation in this file is generally 2 spaces, so this appears to break with the norm.
##########
build-aux/Jenkinsfile.pr:
##########
@@ -61,7 +64,107 @@ pipeline {
stages {
- stage('erlfmt') {
+ stage('Setup Env') {
+ agent {
+ docker {
Review Comment:
Seems like indented too much compared to existing code?
##########
build-aux/Jenkinsfile.pr:
##########
@@ -61,7 +64,68 @@ pipeline {
stages {
+ stage('Docs Check') {
+ // Run docs `make check` stage if any docs changed
+ when { expression { return sh(returnStatus: true, script: docs_changed) == 0 } }
+ agent {
+ docker {
+ image "${DOCKER_IMAGE_BASE}-${LOW_ERLANG_VER}"
+ label 'docker'
+ args "${DOCKER_ARGS}"
+ registryUrl 'https://docker.io/'
+ registryCredentialsId 'dockerhub_creds'
+ }
+ }
+ options {
+ timeout(time: 15, unit: 'MINUTES')
+ }
+ steps {
+ sh '''
+ (cd src/docs && make check)
+ '''
+ }
+ post {
+ cleanup {
+ // UGH see https://issues.jenkins-ci.org/browse/JENKINS-41894
+ sh 'rm -rf ${WORKSPACE}/*'
+ }
+ }
+ } // Docs Check
+
+ stage('Build Docs') {
+ // Build docs separately if only docs changed. If there are other changes, docs are
+ // already built as part of `make dist`
+ when { expression { return (sh(returnStatus: true, script: docs_changed) == 0 && sh(returnStatus: true, script: other_changes) == 1)} }
+ agent {
+ docker {
Review Comment:
Also extra indent here and below.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@couchdb.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [couchdb] nickva commented on pull request #4164: Integrate docs into the main repo
Posted by GitBox <gi...@apache.org>.
nickva commented on PR #4164:
URL: https://github.com/apache/couchdb/pull/4164#issuecomment-1242208623
> Maybe it’s a good idea to define an .editorconfig for the project / projects?
I wonder if emacs could read that? For erlang it's relatively straightforward as we're using erlfmt but for other languages it's a bit unspecified.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@couchdb.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [couchdb] big-r81 commented on pull request #4164: Integrate docs into the main repo
Posted by GitBox <gi...@apache.org>.
big-r81 commented on PR #4164:
URL: https://github.com/apache/couchdb/pull/4164#issuecomment-1242302116
> > Maybe it’s a good idea to define an .editorconfig for the project / projects?
>
> I wonder if emacs could read that? For erlang it's relatively straightforward as we're using erlfmt but for other languages it's a bit unspecified.
https://github.com/editorconfig/editorconfig-emacs
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@couchdb.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [couchdb] nickva commented on pull request #4164: Integrate docs into the main repo
Posted by GitBox <gi...@apache.org>.
nickva commented on PR #4164:
URL: https://github.com/apache/couchdb/pull/4164#issuecomment-1239442611
In the case case of this PR the build stages would look something like this:
<img width="610" alt="Screen Shot 2022-09-07 at 10 05 59 AM" src="https://user-images.githubusercontent.com/211822/188899034-a56b46f2-a57b-4f56-93c7-b1bc7840c81b.png">
* There were docs changed, so `make check` was was run there.
* Since there were other changes besides the docs folder, "Build Docs" stage was skipped, as docs are built as part of the `made dist` stage later.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@couchdb.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [couchdb] nickva merged pull request #4164: Integrate docs into the main repo
Posted by GitBox <gi...@apache.org>.
nickva merged PR #4164:
URL: https://github.com/apache/couchdb/pull/4164
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@couchdb.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [couchdb] nickva commented on pull request #4164: Integrate docs into the main repo
Posted by GitBox <gi...@apache.org>.
nickva commented on PR #4164:
URL: https://github.com/apache/couchdb/pull/4164#issuecomment-1241453546
Good points, @big-r81
RTD allows configuring which branches/tags to build. I think we could keep `stable` (which is an alias to `3.2.2`) and `latest`. `latest` is automatically built from `main`. `stable` can be either an explicit branch, or if that's missing it's automatically the highest semver release tag (the one we use). But our `3.2.2` tag in the main repo won't build the moved docs. So thinking of making a `3.2.2.post1` tag/branch (see https://peps.python.org/pep-0440/#post-releases about semver for post releases) with the integrated docs for 3.2.2 for that case.
As for archiving we could just update the main branch and put just a readme file indicating to move the pull request to the main repo.. After some time we can archive it too.
Unfortunately the pending PRs would have to be re-targeted for the main repo.
I think there would be some links / example readme changes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@couchdb.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [couchdb] nickva commented on pull request #4164: Integrate docs into the main repo
Posted by GitBox <gi...@apache.org>.
nickva commented on PR #4164:
URL: https://github.com/apache/couchdb/pull/4164#issuecomment-1242160115
> Have a few comments, but it appears I was too late!
It’s never too late! Will fix it in a separate PR. Thanks for taking a look, @jaydoane
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@couchdb.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org