matthew-brett/gitwash

Workflow using git

Gitwash

A set of documents and an example repository to describe starting with github and a git workflow.

Our idea is that many projects may have the same workflow, more or less. Each project needs docs that have exact project-specific command lines for use with git and github.

It seems a shame to type all this out for every project, when a lot of it is the same.

Gitwash is one way of solving this problem.

• You can build the gitwash documents directly to review your workflow.
• The documents designed for re-use in different projects are in the gitwash subdirectory.
• In these documents, we've encoded the various strings you will want to replace with strings in ALL CAPS. The PROJECTNAME is the name of the project as it appears in text - for example IPython. REPONAME is the name of the repository (e.g ipython), and MAIN_GH_USER is the main github user (the user for the central github repository - or the name of the github "organization"). This results in links to your project repository of the form github.com/MAIN_GH_USER/REPONAME.git.

• The script gitwash_dumper.py will checkout the gitwash repository, do a search and replace on these strings and replace them with the ones you want, and then output these into your own docs in a place that you choose. You might want a copy of this tool somewhere in your repository. You can refresh it from time to time with:

  curl -O https://raw.githubusercontent.com/matthew-brett/gitwash/main/gitwash_dumper.py

  For IPython, PROJECTNAME is 'IPython', REPONAME is 'ipython', and the MAIN_GH_USER is also 'ipython'. An example command for ipython might then be:

  gitwash_dumper.py doc/devel IPython --repo-name=ipython --github-user=ipython \
     --project-url=https://ipython.org \
     --project-ml-url=https://mail.scipy.org/mailman/listinfo/IPython-dev

  to dump the search / replaced docs into the doc/devel/gitwash directory.

• In the command above you'll notice that you also have to add your project main URL with the --project-url option, and the mailing list URL with the --project-ml-url option. That is the standard way to add your own links into the documentation.

• You might want to have a Makefile target to update gitwash automatically from the sources. For example, in the nipy docs Makefile, we have:

  gitwash-update:
     python ../tools/gitwash_dumper.py devel/guidelines nipy \
         --project-url=https://nipy.org/ \
         --project-ml-url=https://mail.scipy.org/mailman/listinfo/nipy-devel

There's an example build of gitwash at https://matthew-brett.github.io/pydagogue/gitwash_build.html

gitwash's Issues

Some git links dead

Some of the links found in gitwash/git_links.inc are dead.

Please see the matplotlib pull request which fixed these for said project.

Outdated "git://" still appears in various places

For example, following this page results in:

$ git clone git://github.com/nipy/nibabel.git
Cloning into 'nibabel'...
fatal: remote error: 
  The unauthenticated git protocol on port 9418 is no longer supported.
Please see https://github.blog/2021-09-01-improving-git-protocol-security-github/ for more information.

sample code blocks should specify language as sh

Currently, code blocks in doc produced by gitwash do not specify a language (e.g. https://raw.githubusercontent.com/matthew-brett/gitwash/master/gitwash/patching.rst, note the bare ::). As a consequence, they are highlighted as python code if the project defaults to such a language, e.g. http://matplotlib.org/devel/gitwash/patching.html#overview.

It should be sufficient to add a highlight directive (http://www.sphinx-doc.org/en/stable/markup/code.html#directive-highlight) at the top of every gitwash file (I think).

Suggest change of main title...

I think this is a great idea. But the title (in index.rst) as it appears in other documents is IMHO not very descriptive. For matplotlib it says "Working with Matplotlib source code". That is vague, and doesn't indicate anything about "git" or "GitHub" to me and I never thought to click on that link (particularly when "Contributing" is so prominent).

I'd suggest something with GitHub in it: i.e. "Working with Matplotlib code using git and GitHub" or "Using git and Github to contribute to Matplotlib".

README.rst instead of README

Github will recognize the ReST format if you use a proper extension for your README file.

• https://github.com/github/markup/blob/master/lib/github/markups.rb

Syntax error in gitwash_dumper.py

Hi
When building with Python 3.6/3.8 and running the tests in scikit-fuzzy, gitwash_dumper.py has a syntax error in the print statement on line 82, needs extra parentheses.

diff -Naur a/docs/tools/gitwash/gitwash_dumper.py b/docs/tools/gitwash/gitwash_dumper.py
--- a/docs/tools/gitwash/gitwash_dumper.py	2020-10-03 13:56:42.000000000 -0500
+++ b/docs/tools/gitwash/gitwash_dumper.py	2021-02-08 10:07:05.385419866 -0600
@@ -79,7 +79,7 @@
     for rep_glob in rep_globs:
         fnames += fnmatch.filter(out_fnames, rep_glob)
     if verbose:
-        print '\n'.join(fnames)
+        print ('\n'.join(fnames))
     for fname in fnames:
         filename_search_replace(replace_pairs, fname, False)
         for in_exp, out_exp in renames: