Uploaded image for project: 'Swift Driver'
  1. Swift Driver
  2. SWIFT-228

Ensure that docs are updated when public API changes are made

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Major - P3
    • Resolution: Done
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: None
    • Labels:
      None

      Description

      Right now, we have to just remember to regenerate docs when a public facing change is made. It is excessive to do it on every commit, since often changes are just internal.
      However, running make documentation will always generate a diff even when no public changes are made, because every file is updated with a "last updated" date.

      may.hoque@10gen.com suggested that we could determine when changes are needed by taking a diff between the result of make documentation on master and the result of make documentation on the PR. There should only be a difference there when changes are actually needed.

      While we might include that as a test run on Travis, we don't want it to run on PRs, as it would force every PR with docs changes to include them in the PR to pass CI. Given the number of files that get modified, this is really annoying for a PR reviewer. So ideally, this would only run on master on Travis, and a broken build would alert the committer they need to make a second "regenerate docs" commit.

      We should figure out the best way to incorporate this.

      Alternatively, we could only update docs when we tag a release. in that case, we should figure out how to force regenerating docs when we do that. The downside of that is anything we forgot to document up till then would need to be taken care of at the end when we release which might be annoying; doing it the other way would force us to document things as we write them. However, since it would be annoying to have to deal with forgotten documentation when we release, we could try to avoid this by turning on a swiftlint rule for complaining when a declaration does not have documentation attached to it which can now be done with missing_docs.

      Building from the above idea, a finer grained approach of running an Evergreen-like (think Waterfall) task on every commit/merge to master via Travis (and not on every PR) may allow us to deal with the issue of forgotten documentation pretty soon after closing a ticket, as opposed to during release.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              Unassigned Unassigned
              Reporter:
              kaitlin.mahar Kaitlin Mahar
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: