taskReproducible paper template - Tasks: task #15320, Revising the *Commit Message*...

 
 

You are not allowed to post comments on this tracker with your current authentication level.

task #15320: Revising the *Commit Message* section of README-hacking.md

Submitted by:  Mohammadreza Khellat <mkhellat>
Submitted on:  Mon 08 Jul 2019 04:36:39 AM UTC  
 
Should Start On:  Mon 08 Jul 2019 12:00:00 AM UTC Should be Finished on:  Mon 08 Jul 2019 12:00:00 AM UTC
Category:  None Priority:  7 - High
Status:  In Progress Privacy:  Public
Percent Complete:  0% Assigned to:  None
Open/Closed:  Open Effort:  0.00

Fri 19 Jul 2019 04:55:39 PM UTC, comment #1: 

Thanks for raising this point Mohammadreza,

About the mandatory point, the thing you should consider is that in a Free or Open Source Software, the source code itself must be easily readable, like a book.

Imagine a multi-author book/paper. Is one paragraph written in one font size, line width, or line spacing (which is the subjective choice of its author), while the next paragraph has different typographical settings because another author wrote it? Will such a book be easily readable by a third person? Won't these different styles discourage group work?

Because of this, in free software projects, there are usually standards to follow for the style of the code. For example, in the GNU Coding Standards, there is a whole section on "Formatting your source code". If you look on the first line it says: "Please keep the length of source lines to 79 characters or less", and following that it is suggested stylistic/subjective formatting patterns in the code that have no effect on the compiling/running of the program. They are just defined because once everyone follows them, the code will be readable/welcome by others.

Another nice example is Python's PEP8 style guide. Have a look at the contents and types of recommendations to see what I mean. In many cases, people will even not consider looking into a Python code if it doesn't follow these styles (since it slows them down, and it shows the person didn't care about sharing the code with others to read).

If you inspect any professional project that involves more than one person, you will see similar style guides. For example see the LSST C++ Style Guide (for the data analysis software of the Large Synoptic Survey Telescope, that will start operations soon), in particular note all the "SHOULD"s and "MUST"s.

On the second point of providing a description of why something has been set. Of course! If you feel the reason behind something is not clear, please post it here so we add some explanation.

Hopefully later when we write a full manual, we'll have more space for this. But there is also Gnuastro's Coding conventions that give a little more detail.

Mohammad Akhlaghi <makhlaghi>
Project Administrator
Mon 08 Jul 2019 04:36:39 AM UTC, original submission:  

Follwoing some discussions around mandatory and low-level requirements in task #15262: Source code downloads and Job manager, I am suggesting a revision of the Commit Message section of README-hacking.md.

My proposed revision includes

  • removing the term mandatory from the section, and
  • providing a general description of the suggested proints alongside a brief explanation why it is suggested.
Mohammadreza Khellat <mkhellat>
Project Member

 

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by makhlaghi (Posted a comment)
  • -email is unavailable- added by mkhellat (Submitted the item)
  • -email is unavailable- added by mkhellat
  • -email is unavailable- added by mkhellat
  •  

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

     

     

    Follow 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2019-07-08 mkhellat StatusNone => In Progress
    2019-07-08 mkhellat Carbon-Copy- => Added makhlaghi
        Carbon-Copy- => Added infantesainz

    Back to the top


    Powered by Savane 3.5