Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Developer notes / Contributing #43

Open
3 of 6 tasks
raphaeltimbo opened this issue May 10, 2017 · 10 comments
Open
3 of 6 tasks

Developer notes / Contributing #43

raphaeltimbo opened this issue May 10, 2017 · 10 comments

Comments

@raphaeltimbo
Copy link
Collaborator

raphaeltimbo commented May 10, 2017 •
edited
Loading

Currently we have some files inside the project that give some guidance on how to develop code for this project, but I think it would be good if we could discuss which files we should have and what they should contain.
Currently we have notes on:
readme.rst
vibration_toolbox/readme.rst
developer_notes.rst
create_distro.rst

I believe we could merge some of these files in a CONTRIBUTING.rst or something like that, just to make it easier to get the information.
Would like to hear your opinions @josephcslater @AnushaAnisetti

Regarding the content of the files, I think we should cover:

EDITING THIS PART AS WE DISCUSS

  • Where to find support in case of doubts on how to use the toolbox.

  • Explain where and how to report bugs.

CONTRIBUTING.rst See #42

  • Explain standards adopted for the project such as numpydoc conventions

  • Explain how to run tests

  • Steps to take before submitting to Github.

  • ...

Feel free do add items here.
@josephcslater
Copy link
Member

I agree. You are seeing how I address my memory as I get older- I leave notes where I need them. I this case, taking seconds to jot things down potentially saves hours. However, there is enough that it is messy and should be consolidated.

FWIW: Anusha is not new to Python, but very fresh, more so than I was over a year ago. So, she will certainly need our support. She is not new to modeling mechanics/vibration, but to the language and all of the structure of a project. I only started to learn how to put together a project with you last year. I have more students who will likely be joining in and this may very well be used as a place they can try things (of course, without them having the ability to merge without approval).

So: I like the name you give. I support 100% compatibility with NumPy practices and standards. Making it rst may be kinder than markdown as I do anticipate this being an entry point for programming (keeping the two straight in my head sometimes baffles me).

Second, I think it should steer non-developers directly to the manual. Likewise, the manual should steer prospective developers to this document. By doing this, they each can focus on the intended audience.

With that, the manual should contain:

  1. Where to find support in case of doubts on how to use the toolbox.

  2. Explain where and how to report bugs.

  3. ...

While the CONTRIBUTING.rst file should contain

  1. Explain standards adopted for the project such as numpydoc conventions

  2. Explain how to run tests Adding how to run tests on developer notes. #42

  3. Expected practices (forking/pull requests). I've only given Raphael and myself the ability to directly change the main fork. Branching can be tedious, but I think it's best to keep the number of direct hands controlled. Anusha still needs oversite more than either of us. You've had better behavior than I in forking and merging, but I will likely not be doing as much of my own forks as others. I'll be helping, guiding, and managing more than contributing in a major way as I'll be focused on my other two major projects... neither of which is yet off the ground.

  4. ...

The MAKEFILE now has help, so some of the documentation on making releases is no longer necessary.

@AnushaAnisetti
Copy link
Contributor

AnushaAnisetti commented May 10, 2017 via email

@raphaeltimbo
Copy link
Collaborator Author

I have updated my initial comments based on your replies.
I have changed the developer_notes.rst file to CONTRIBUTING.rst.
Inside the contributing file I have tried to describe the process to contribute code and I have also added a final section to main developers (with things like how to make distribution).
If you all agree I think it is safe to delete the readme.rst file inside the /docs and the create_distro.rst.

Regarding the first part "Where to find support in case of doubts on how to use the toolbox." do you think it would be ok to refer to the github/issues as well? Normally projects have a forum or mailing list for this kind of stuff, but since we don't have that, I think it would not be a bad think (at least for now) to use the issues part for this purpose.

@AnushaAnisetti
Copy link
Contributor

Raphael,

Could you please provide me your e-mail ID for few developer questions? I will not take much time.
I can be reached at [email protected]

@raphaeltimbo
Copy link
Collaborator Author

Of course! It is [email protected]

@josephcslater
Copy link
Member

@raphaeltimbo Yes, directing to issues is appropriate. Do you think we need to set up a mailing list? Wow- this has developed quickly.

@josephcslater
Copy link
Member

@raphaeltimbo I updated CONTRIBUTING.rst. Note that most of the "help docs" were made unnecessary by the Makefile.

We could add "pull-request" as an option which would run pytest, commit, etc. if you think that would be helpful? It may be for @AnushaAnisetti as she isn't Unix experienced, but she may have make working now.

@raphaeltimbo
Copy link
Collaborator Author

Regarding the pull-request command in the make file, that could be an option, but I don't know how that would be implemented since my knowledge of 'make' is not that much.
I actually tend to use pycharm git integration to commit and then push new branches to the repository. After that I use the github site to open the pull-request and to check if travis is passing.

@josephcslater
Copy link
Member

So, I only learned to create the Makefile recently. You only need use it.

From the top of the repository, in a terminal, you can type make and it will provide help (added a few days ago).

There is a slew of commands for building distribution files, documents, making releases, pushing to pypi, etc. So, my making the Makefile took out the need for my own instructions (as they are listed as instructions for each operation in the Makefile.).

I've never used the pycharm git tools. I'm mostly using spyder and jupyter for my work, although I then use Atom for "cleanup". Atom has git integration as well, but I tend to use the github app (I'm on a Mac), although I've started to really like GitKraken, which is multiplatform and gives a nice visualization of what's going on.

@raphaeltimbo
Copy link
Collaborator Author

Regarding the mailing list, I would prefer to use only the issues. I think that is better if we keep things in only one. I thing I notice is that we can label an issue as a question, using that we can keep track of the real bugs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@josephcslater @AnushaAnisetti @raphaeltimbo